| .\" Man page generated from reStructuredText. |
| . |
| .TH "CMAKE-PROPERTIES" "7" "Apr 12, 2022" "3.23.1" "CMake" |
| .SH NAME |
| cmake-properties \- CMake Properties Reference |
| . |
| .nr rst2man-indent-level 0 |
| . |
| .de1 rstReportMargin |
| \\$1 \\n[an-margin] |
| level \\n[rst2man-indent-level] |
| level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| - |
| \\n[rst2man-indent0] |
| \\n[rst2man-indent1] |
| \\n[rst2man-indent2] |
| .. |
| .de1 INDENT |
| .\" .rstReportMargin pre: |
| . RS \\$1 |
| . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] |
| . nr rst2man-indent-level +1 |
| .\" .rstReportMargin post: |
| .. |
| .de UNINDENT |
| . RE |
| .\" indent \\n[an-margin] |
| .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| .nr rst2man-indent-level -1 |
| .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| .in \\n[rst2man-indent\\n[rst2man-indent-level]]u |
| .. |
| .SH PROPERTIES OF GLOBAL SCOPE |
| .SS ALLOW_DUPLICATE_CUSTOM_TARGETS |
| .sp |
| Allow duplicate custom targets to be created. |
| .sp |
| Normally CMake requires that all targets built in a project have |
| globally unique logical names (see policy \fBCMP0002\fP). |
| This is necessary to generate meaningful project file names in |
| \fBXcode\fP and Visual Studio Generators IDE |
| generators. It also allows the target names to be referenced |
| unambiguously. |
| .sp |
| Makefile generators are capable of supporting duplicate \fBadd_custom_target()\fP |
| names. For projects that care only about Makefile Generators and do |
| not wish to support \fBXcode\fP or Visual Studio Generators IDE |
| generators, one may set this property to \fBTrue\fP |
| to allow duplicate custom targets. The property |
| allows multiple \fBadd_custom_target()\fP command calls in different |
| directories to specify the same target name. However, setting this |
| property will cause non\-Makefile generators to produce an error and |
| refuse to generate the project. |
| .SS AUTOGEN_SOURCE_GROUP |
| .sp |
| New in version 3.9. |
| |
| .sp |
| Name of the \fBsource_group()\fP for \fBAUTOMOC\fP, |
| \fBAUTORCC\fP and \fBAUTOUIC\fP generated files. |
| .sp |
| Files generated by \fBAUTOMOC\fP, \fBAUTORCC\fP and |
| \fBAUTOUIC\fP are not always known at configure time and therefore can\(aqt |
| be passed to \fBsource_group()\fP\&. |
| \fI\%AUTOGEN_SOURCE_GROUP\fP can be used instead to generate or select |
| a source group for \fBAUTOMOC\fP, \fBAUTORCC\fP and |
| \fBAUTOUIC\fP generated files. |
| .sp |
| For \fBAUTOMOC\fP, \fBAUTORCC\fP and \fBAUTOUIC\fP specific |
| overrides see \fBAUTOMOC_SOURCE_GROUP\fP, \fBAUTORCC_SOURCE_GROUP\fP |
| and \fBAUTOUIC_SOURCE_GROUP\fP respectively. |
| .SS AUTOGEN_TARGETS_FOLDER |
| .sp |
| Name of \fBFOLDER\fP for \fB*_autogen\fP targets that are added |
| automatically by CMake for targets for which \fBAUTOMOC\fP is enabled. |
| .sp |
| If not set, CMake uses the \fBFOLDER\fP property of the parent target as a |
| default value for this property. See also the documentation for the |
| \fBFOLDER\fP target property and the \fBAUTOMOC\fP target property. |
| .SS AUTOMOC_SOURCE_GROUP |
| .sp |
| New in version 3.9. |
| |
| .sp |
| Name of the \fBsource_group()\fP for \fBAUTOMOC\fP generated files. |
| .sp |
| When set this is used instead of \fBAUTOGEN_SOURCE_GROUP\fP for |
| files generated by \fBAUTOMOC\fP\&. |
| .SS AUTOMOC_TARGETS_FOLDER |
| .sp |
| Name of \fBFOLDER\fP for \fB*_autogen\fP targets that are added automatically by |
| CMake for targets for which \fBAUTOMOC\fP is enabled. |
| .sp |
| This property is obsolete. Use \fBAUTOGEN_TARGETS_FOLDER\fP instead. |
| .sp |
| If not set, CMake uses the \fBFOLDER\fP property of the parent target as a |
| default value for this property. See also the documentation for the |
| \fBFOLDER\fP target property and the \fBAUTOMOC\fP target property. |
| .SS AUTORCC_SOURCE_GROUP |
| .sp |
| New in version 3.9. |
| |
| .sp |
| Name of the \fBsource_group()\fP for \fBAUTORCC\fP generated files. |
| .sp |
| When set this is used instead of \fBAUTOGEN_SOURCE_GROUP\fP for |
| files generated by \fBAUTORCC\fP\&. |
| .SS AUTOUIC_SOURCE_GROUP |
| .sp |
| New in version 3.21. |
| |
| .sp |
| Name of the \fBsource_group()\fP for \fBAUTOUIC\fP generated files. |
| .sp |
| When set this is used instead of \fBAUTOGEN_SOURCE_GROUP\fP for |
| files generated by \fBAUTOUIC\fP\&. |
| .SS CMAKE_C_KNOWN_FEATURES |
| .sp |
| New in version 3.1. |
| |
| .sp |
| List of C features known to this version of CMake. |
| .sp |
| The features listed in this global property may be known to be available to the |
| C compiler. If the feature is available with the C compiler, it will |
| be listed in the \fBCMAKE_C_COMPILE_FEATURES\fP variable. |
| .sp |
| The features listed here may be used with the \fBtarget_compile_features()\fP |
| command. See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| The features known to this version of CMake are listed below. |
| .SS High level meta features indicating C standard support |
| .sp |
| New in version 3.8. |
| |
| .INDENT 0.0 |
| .TP |
| .B \fBc_std_90\fP |
| Compiler mode is at least C 90. |
| .TP |
| .B \fBc_std_99\fP |
| Compiler mode is at least C 99. |
| .TP |
| .B \fBc_std_11\fP |
| Compiler mode is at least C 11. |
| .TP |
| .B \fBc_std_17\fP |
| New in version 3.21. |
| |
| .sp |
| Compiler mode is at least C 17. |
| .TP |
| .B \fBc_std_23\fP |
| New in version 3.21. |
| |
| .sp |
| Compiler mode is at least C 23. |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| If the compiler\(aqs default standard level is at least that |
| of the requested feature, CMake may omit the \fB\-std=\fP flag. |
| The flag may still be added if the compiler\(aqs default extensions mode |
| does not match the \fB<LANG>_EXTENSIONS\fP target property, |
| or if the \fB<LANG>_STANDARD\fP target property is set. |
| .UNINDENT |
| .UNINDENT |
| .SS Low level individual compile features |
| .INDENT 0.0 |
| .TP |
| .B \fBc_function_prototypes\fP |
| Function prototypes, as defined in \fBISO/IEC 9899:1990\fP\&. |
| .TP |
| .B \fBc_restrict\fP |
| \fBrestrict\fP keyword, as defined in \fBISO/IEC 9899:1999\fP\&. |
| .TP |
| .B \fBc_static_assert\fP |
| Static assert, as defined in \fBISO/IEC 9899:2011\fP\&. |
| .TP |
| .B \fBc_variadic_macros\fP |
| Variadic macros, as defined in \fBISO/IEC 9899:1999\fP\&. |
| .UNINDENT |
| .SS CMAKE_CUDA_KNOWN_FEATURES |
| .sp |
| New in version 3.17. |
| |
| .sp |
| List of CUDA features known to this version of CMake. |
| .sp |
| The features listed in this global property may be known to be available to the |
| CUDA compiler. If the feature is available with the C++ compiler, it will |
| be listed in the \fBCMAKE_CUDA_COMPILE_FEATURES\fP variable. |
| .sp |
| The features listed here may be used with the \fBtarget_compile_features()\fP |
| command. See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| The features known to this version of CMake are: |
| .INDENT 0.0 |
| .TP |
| .B \fBcuda_std_03\fP |
| Compiler mode is at least CUDA/C++ 03. |
| .TP |
| .B \fBcuda_std_11\fP |
| Compiler mode is at least CUDA/C++ 11. |
| .TP |
| .B \fBcuda_std_14\fP |
| Compiler mode is at least CUDA/C++ 14. |
| .TP |
| .B \fBcuda_std_17\fP |
| Compiler mode is at least CUDA/C++ 17. |
| .TP |
| .B \fBcuda_std_20\fP |
| Compiler mode is at least CUDA/C++ 20. |
| .TP |
| .B \fBcuda_std_23\fP |
| New in version 3.20. |
| |
| .sp |
| Compiler mode is at least CUDA/C++ 23. |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| If the compiler\(aqs default standard level is at least that |
| of the requested feature, CMake may omit the \fB\-std=\fP flag. |
| The flag may still be added if the compiler\(aqs default extensions mode |
| does not match the \fB<LANG>_EXTENSIONS\fP target property, |
| or if the \fB<LANG>_STANDARD\fP target property is set. |
| .UNINDENT |
| .UNINDENT |
| .SS CMAKE_CXX_KNOWN_FEATURES |
| .sp |
| New in version 3.1. |
| |
| .sp |
| List of C++ features known to this version of CMake. |
| .sp |
| The features listed in this global property may be known to be available to the |
| C++ compiler. If the feature is available with the C++ compiler, it will |
| be listed in the \fBCMAKE_CXX_COMPILE_FEATURES\fP variable. |
| .sp |
| The features listed here may be used with the \fBtarget_compile_features()\fP |
| command. See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| The features known to this version of CMake are listed below. |
| .SS High level meta features indicating C++ standard support |
| .sp |
| New in version 3.8. |
| |
| .sp |
| The following meta features indicate general support for the associated |
| language standard. It reflects the language support claimed by the compiler, |
| but it does not necessarily imply complete conformance to that standard. |
| .INDENT 0.0 |
| .TP |
| .B \fBcxx_std_98\fP |
| Compiler mode is at least C++ 98. |
| .TP |
| .B \fBcxx_std_11\fP |
| Compiler mode is at least C++ 11. |
| .TP |
| .B \fBcxx_std_14\fP |
| Compiler mode is at least C++ 14. |
| .TP |
| .B \fBcxx_std_17\fP |
| Compiler mode is at least C++ 17. |
| .TP |
| .B \fBcxx_std_20\fP |
| New in version 3.12. |
| |
| .sp |
| Compiler mode is at least C++ 20. |
| .TP |
| .B \fBcxx_std_23\fP |
| New in version 3.20. |
| |
| .sp |
| Compiler mode is at least C++ 23. |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| If the compiler\(aqs default standard level is at least that |
| of the requested feature, CMake may omit the \fB\-std=\fP flag. |
| The flag may still be added if the compiler\(aqs default extensions mode |
| does not match the \fB<LANG>_EXTENSIONS\fP target property, |
| or if the \fB<LANG>_STANDARD\fP target property is set. |
| .UNINDENT |
| .UNINDENT |
| .SS Low level individual compile features |
| .sp |
| For C++ 11 and C++ 14, compilers were sometimes slow to implement certain |
| language features. CMake provided some individual compile features to help |
| projects determine whether specific features were available. These individual |
| features are now less relevant and projects should generally prefer to use the |
| high level meta features instead. Individual compile features are not provided |
| for C++ 17 or later. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for further discussion of |
| the use of individual compile features. |
| .SS Individual features from C++ 98 |
| .INDENT 0.0 |
| .TP |
| .B \fBcxx_template_template_parameters\fP |
| Template template parameters, as defined in \fBISO/IEC 14882:1998\fP\&. |
| .UNINDENT |
| .SS Individual features from C++ 11 |
| .INDENT 0.0 |
| .TP |
| .B \fBcxx_alias_templates\fP |
| Template aliases, as defined in \fI\%N2258\fP\&. |
| .TP |
| .B \fBcxx_alignas\fP |
| Alignment control \fBalignas\fP, as defined in \fI\%N2341\fP\&. |
| .TP |
| .B \fBcxx_alignof\fP |
| Alignment control \fBalignof\fP, as defined in \fI\%N2341\fP\&. |
| .TP |
| .B \fBcxx_attributes\fP |
| Generic attributes, as defined in \fI\%N2761\fP\&. |
| .TP |
| .B \fBcxx_auto_type\fP |
| Automatic type deduction, as defined in \fI\%N1984\fP\&. |
| .TP |
| .B \fBcxx_constexpr\fP |
| Constant expressions, as defined in \fI\%N2235\fP\&. |
| .TP |
| .B \fBcxx_decltype_incomplete_return_types\fP |
| Decltype on incomplete return types, as defined in \fI\%N3276\fP\&. |
| .TP |
| .B \fBcxx_decltype\fP |
| Decltype, as defined in \fI\%N2343\fP\&. |
| .TP |
| .B \fBcxx_default_function_template_args\fP |
| Default template arguments for function templates, as defined in \fI\%DR226\fP |
| .TP |
| .B \fBcxx_defaulted_functions\fP |
| Defaulted functions, as defined in \fI\%N2346\fP\&. |
| .TP |
| .B \fBcxx_defaulted_move_initializers\fP |
| Defaulted move initializers, as defined in \fI\%N3053\fP\&. |
| .TP |
| .B \fBcxx_delegating_constructors\fP |
| Delegating constructors, as defined in \fI\%N1986\fP\&. |
| .TP |
| .B \fBcxx_deleted_functions\fP |
| Deleted functions, as defined in \fI\%N2346\fP\&. |
| .TP |
| .B \fBcxx_enum_forward_declarations\fP |
| Enum forward declarations, as defined in \fI\%N2764\fP\&. |
| .TP |
| .B \fBcxx_explicit_conversions\fP |
| Explicit conversion operators, as defined in \fI\%N2437\fP\&. |
| .TP |
| .B \fBcxx_extended_friend_declarations\fP |
| Extended friend declarations, as defined in \fI\%N1791\fP\&. |
| .TP |
| .B \fBcxx_extern_templates\fP |
| Extern templates, as defined in \fI\%N1987\fP\&. |
| .TP |
| .B \fBcxx_final\fP |
| Override control \fBfinal\fP keyword, as defined in \fI\%N2928\fP, \fI\%N3206\fP and \fI\%N3272\fP\&. |
| .TP |
| .B \fBcxx_func_identifier\fP |
| Predefined \fB__func__\fP identifier, as defined in \fI\%N2340\fP\&. |
| .TP |
| .B \fBcxx_generalized_initializers\fP |
| Initializer lists, as defined in \fI\%N2672\fP\&. |
| .TP |
| .B \fBcxx_inheriting_constructors\fP |
| Inheriting constructors, as defined in \fI\%N2540\fP\&. |
| .TP |
| .B \fBcxx_inline_namespaces\fP |
| Inline namespaces, as defined in \fI\%N2535\fP\&. |
| .TP |
| .B \fBcxx_lambdas\fP |
| Lambda functions, as defined in \fI\%N2927\fP\&. |
| .TP |
| .B \fBcxx_local_type_template_args\fP |
| Local and unnamed types as template arguments, as defined in \fI\%N2657\fP\&. |
| .TP |
| .B \fBcxx_long_long_type\fP |
| \fBlong long\fP type, as defined in \fI\%N1811\fP\&. |
| .TP |
| .B \fBcxx_noexcept\fP |
| Exception specifications, as defined in \fI\%N3050\fP\&. |
| .TP |
| .B \fBcxx_nonstatic_member_init\fP |
| Non\-static data member initialization, as defined in \fI\%N2756\fP\&. |
| .TP |
| .B \fBcxx_nullptr\fP |
| Null pointer, as defined in \fI\%N2431\fP\&. |
| .TP |
| .B \fBcxx_override\fP |
| Override control \fBoverride\fP keyword, as defined in \fI\%N2928\fP, \fI\%N3206\fP |
| and \fI\%N3272\fP\&. |
| .TP |
| .B \fBcxx_range_for\fP |
| Range\-based for, as defined in \fI\%N2930\fP\&. |
| .TP |
| .B \fBcxx_raw_string_literals\fP |
| Raw string literals, as defined in \fI\%N2442\fP\&. |
| .TP |
| .B \fBcxx_reference_qualified_functions\fP |
| Reference qualified functions, as defined in \fI\%N2439\fP\&. |
| .TP |
| .B \fBcxx_right_angle_brackets\fP |
| Right angle bracket parsing, as defined in \fI\%N1757\fP\&. |
| .TP |
| .B \fBcxx_rvalue_references\fP |
| R\-value references, as defined in \fI\%N2118\fP\&. |
| .TP |
| .B \fBcxx_sizeof_member\fP |
| Size of non\-static data members, as defined in \fI\%N2253\fP\&. |
| .TP |
| .B \fBcxx_static_assert\fP |
| Static assert, as defined in \fI\%N1720\fP\&. |
| .TP |
| .B \fBcxx_strong_enums\fP |
| Strongly typed enums, as defined in \fI\%N2347\fP\&. |
| .TP |
| .B \fBcxx_thread_local\fP |
| Thread\-local variables, as defined in \fI\%N2659\fP\&. |
| .TP |
| .B \fBcxx_trailing_return_types\fP |
| Automatic function return type, as defined in \fI\%N2541\fP\&. |
| .TP |
| .B \fBcxx_unicode_literals\fP |
| Unicode string literals, as defined in \fI\%N2442\fP\&. |
| .TP |
| .B \fBcxx_uniform_initialization\fP |
| Uniform initialization, as defined in \fI\%N2640\fP\&. |
| .TP |
| .B \fBcxx_unrestricted_unions\fP |
| Unrestricted unions, as defined in \fI\%N2544\fP\&. |
| .TP |
| .B \fBcxx_user_literals\fP |
| User\-defined literals, as defined in \fI\%N2765\fP\&. |
| .TP |
| .B \fBcxx_variadic_macros\fP |
| Variadic macros, as defined in \fI\%N1653\fP\&. |
| .TP |
| .B \fBcxx_variadic_templates\fP |
| Variadic templates, as defined in \fI\%N2242\fP\&. |
| .UNINDENT |
| .SS Individual features from C++ 14 |
| .INDENT 0.0 |
| .TP |
| .B \fBcxx_aggregate_default_initializers\fP |
| Aggregate default initializers, as defined in \fI\%N3605\fP\&. |
| .TP |
| .B \fBcxx_attribute_deprecated\fP |
| \fB[[deprecated]]\fP attribute, as defined in \fI\%N3760\fP\&. |
| .TP |
| .B \fBcxx_binary_literals\fP |
| Binary literals, as defined in \fI\%N3472\fP\&. |
| .TP |
| .B \fBcxx_contextual_conversions\fP |
| Contextual conversions, as defined in \fI\%N3323\fP\&. |
| .TP |
| .B \fBcxx_decltype_auto\fP |
| \fBdecltype(auto)\fP semantics, as defined in \fI\%N3638\fP\&. |
| .TP |
| .B \fBcxx_digit_separators\fP |
| Digit separators, as defined in \fI\%N3781\fP\&. |
| .TP |
| .B \fBcxx_generic_lambdas\fP |
| Generic lambdas, as defined in \fI\%N3649\fP\&. |
| .TP |
| .B \fBcxx_lambda_init_captures\fP |
| Initialized lambda captures, as defined in \fI\%N3648\fP\&. |
| .TP |
| .B \fBcxx_relaxed_constexpr\fP |
| Relaxed constexpr, as defined in \fI\%N3652\fP\&. |
| .TP |
| .B \fBcxx_return_type_deduction\fP |
| Return type deduction on normal functions, as defined in \fI\%N3386\fP\&. |
| .TP |
| .B \fBcxx_variable_templates\fP |
| Variable templates, as defined in \fI\%N3651\fP\&. |
| .UNINDENT |
| .SS CMAKE_ROLE |
| .sp |
| New in version 3.14. |
| |
| .sp |
| Tells what mode the current running script is in. Could be one of several |
| values: |
| .INDENT 0.0 |
| .TP |
| .B \fBPROJECT\fP |
| Running in project mode (processing a \fBCMakeLists.txt\fP file). |
| .TP |
| .B \fBSCRIPT\fP |
| Running in \fB\-P\fP script mode. |
| .TP |
| .B \fBFIND_PACKAGE\fP |
| Running in \fB\-\-find\-package\fP mode. |
| .TP |
| .B \fBCTEST\fP |
| Running in CTest script mode. |
| .TP |
| .B \fBCPACK\fP |
| Running in CPack. |
| .UNINDENT |
| .SS DEBUG_CONFIGURATIONS |
| .sp |
| Specify which configurations are for debugging. |
| .sp |
| The value must be a semi\-colon separated list of configuration names. |
| Currently this property is used only by the \fBtarget_link_libraries()\fP |
| command. Additional uses may be defined in the future. |
| .sp |
| This property must be set at the top level of the project and before |
| the first \fBtarget_link_libraries()\fP command invocation. If any entry in |
| the list does not match a valid configuration for the project the |
| behavior is undefined. |
| .SS DISABLED_FEATURES |
| .sp |
| List of features which are disabled during the CMake run. |
| .sp |
| List of features which are disabled during the CMake run. By default |
| it contains the names of all packages which were not found. This is |
| determined using the \fB<NAME>_FOUND\fP variables. Packages which are |
| searched \fBQUIET\fP are not listed. A project can add its own features to |
| this list. This property is used by the macros in |
| \fBFeatureSummary.cmake\fP\&. |
| .SS ECLIPSE_EXTRA_CPROJECT_CONTENTS |
| .sp |
| New in version 3.12. |
| |
| .sp |
| Additional contents to be inserted into the generated Eclipse cproject file. |
| .sp |
| The cproject file defines the CDT specific information. Some third party IDE\(aqs |
| are based on Eclipse with the addition of other information specific to that IDE. |
| Through this property, it is possible to add this additional contents to |
| the generated project. |
| It is expected to contain valid XML. |
| .sp |
| Also see the \fBECLIPSE_EXTRA_NATURES\fP property. |
| .SS ECLIPSE_EXTRA_NATURES |
| .sp |
| List of natures to add to the generated Eclipse project file. |
| .sp |
| Eclipse projects specify language plugins by using natures. This property |
| should be set to the unique identifier for a nature (which looks like a Java |
| package name). |
| .sp |
| Also see the \fBECLIPSE_EXTRA_CPROJECT_CONTENTS\fP property. |
| .SS ENABLED_FEATURES |
| .sp |
| List of features which are enabled during the CMake run. |
| .sp |
| List of features which are enabled during the CMake run. By default |
| it contains the names of all packages which were found. This is |
| determined using the \fB<NAME>_FOUND\fP variables. Packages which are |
| searched \fBQUIET\fP are not listed. A project can add its own features to |
| this list. This property is used by the macros in |
| \fBFeatureSummary.cmake\fP\&. |
| .SS ENABLED_LANGUAGES |
| .sp |
| Read\-only property that contains the list of currently enabled languages |
| .sp |
| Set to list of currently enabled languages. |
| .SS FIND_LIBRARY_USE_LIB32_PATHS |
| .sp |
| New in version 3.7. |
| |
| .sp |
| Whether the \fBfind_library()\fP command should automatically search |
| \fBlib32\fP directories. |
| .sp |
| \fBFIND_LIBRARY_USE_LIB32_PATHS\fP is a boolean specifying whether the |
| \fBfind_library()\fP command should automatically search the \fBlib32\fP |
| variant of directories called \fBlib\fP in the search path when building 32\-bit |
| binaries. |
| .sp |
| See also the \fBCMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX\fP variable. |
| .SS FIND_LIBRARY_USE_LIB64_PATHS |
| .sp |
| Whether \fBfind_library()\fP should automatically search lib64 |
| directories. |
| .sp |
| FIND_LIBRARY_USE_LIB64_PATHS is a boolean specifying whether the |
| \fBfind_library()\fP command should automatically search the lib64 |
| variant of directories called lib in the search path when building |
| 64\-bit binaries. |
| .sp |
| See also the \fBCMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX\fP variable. |
| .SS FIND_LIBRARY_USE_LIBX32_PATHS |
| .sp |
| New in version 3.9. |
| |
| .sp |
| Whether the \fBfind_library()\fP command should automatically search |
| \fBlibx32\fP directories. |
| .sp |
| \fBFIND_LIBRARY_USE_LIBX32_PATHS\fP is a boolean specifying whether the |
| \fBfind_library()\fP command should automatically search the \fBlibx32\fP |
| variant of directories called \fBlib\fP in the search path when building |
| x32\-abi binaries. |
| .sp |
| See also the \fBCMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX\fP variable. |
| .SS FIND_LIBRARY_USE_OPENBSD_VERSIONING |
| .sp |
| Whether \fBfind_library()\fP should find OpenBSD\-style shared |
| libraries. |
| .sp |
| This property is a boolean specifying whether the |
| \fBfind_library()\fP command should find shared libraries with |
| OpenBSD\-style versioned extension: ".so.<major>.<minor>". The |
| property is set to true on OpenBSD and false on other platforms. |
| .SS GENERATOR_IS_MULTI_CONFIG |
| .sp |
| New in version 3.9. |
| |
| .sp |
| Read\-only property that is true on multi\-configuration generators. |
| .sp |
| True when using a multi\-configuration generator such as: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBNinja Multi\-Config\fP |
| .IP \(bu 2 |
| Visual Studio Generators |
| .IP \(bu 2 |
| \fBXcode\fP |
| .UNINDENT |
| .sp |
| Multi\-config generators use \fBCMAKE_CONFIGURATION_TYPES\fP |
| as the set of configurations and ignore \fBCMAKE_BUILD_TYPE\fP\&. |
| .SS GLOBAL_DEPENDS_DEBUG_MODE |
| .sp |
| Enable global target dependency graph debug mode. |
| .sp |
| CMake automatically analyzes the global inter\-target dependency graph |
| at the beginning of native build system generation. This property |
| causes it to display details of its analysis to stderr. |
| .SS GLOBAL_DEPENDS_NO_CYCLES |
| .sp |
| Disallow global target dependency graph cycles. |
| .sp |
| CMake automatically analyzes the global inter\-target dependency graph |
| at the beginning of native build system generation. It reports an |
| error if the dependency graph contains a cycle that does not consist |
| of all STATIC library targets. This property tells CMake to disallow |
| all cycles completely, even among static libraries. |
| .SS IN_TRY_COMPILE |
| .sp |
| Read\-only property that is true during a try\-compile configuration. |
| .sp |
| True when building a project inside a \fBtry_compile()\fP or |
| \fBtry_run()\fP command. |
| .SS JOB_POOLS |
| .sp |
| Ninja only: List of available pools. |
| .sp |
| A pool is a named integer property and defines the maximum number |
| of concurrent jobs which can be started by a rule assigned to the pool. |
| The \fI\%JOB_POOLS\fP property is a semicolon\-separated list of |
| pairs using the syntax NAME=integer (without a space after the equality sign). |
| .sp |
| For instance: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(GLOBAL PROPERTY JOB_POOLS two_jobs=2 ten_jobs=10) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Defined pools could be used globally by setting |
| \fBCMAKE_JOB_POOL_COMPILE\fP and \fBCMAKE_JOB_POOL_LINK\fP |
| or per target by setting the target properties |
| \fBJOB_POOL_COMPILE\fP and \fBJOB_POOL_LINK\fP\&. |
| \fBCustom commands\fP and |
| \fBcustom targets\fP can specify pools using the |
| option \fBJOB_POOL\fP\&. |
| Using a pool that is not defined by \fI\%JOB_POOLS\fP causes |
| an error by ninja at build time. |
| .sp |
| If not set, this property uses the value of the \fBCMAKE_JOB_POOLS\fP |
| variable. |
| .sp |
| Build targets provided by CMake that are meant for individual interactive |
| use, such as \fBinstall\fP, are placed in the \fBconsole\fP pool automatically. |
| .SS PACKAGES_FOUND |
| .sp |
| List of packages which were found during the CMake run. |
| .sp |
| List of packages which were found during the CMake run. Whether a |
| package has been found is determined using the <NAME>_FOUND variables. |
| .SS PACKAGES_NOT_FOUND |
| .sp |
| List of packages which were not found during the CMake run. |
| .sp |
| List of packages which were not found during the CMake run. Whether a |
| package has been found is determined using the <NAME>_FOUND variables. |
| .SS PREDEFINED_TARGETS_FOLDER |
| .sp |
| Name of FOLDER for targets that are added automatically by CMake. |
| .sp |
| If not set, CMake uses "CMakePredefinedTargets" as a default value for |
| this property. Targets such as INSTALL, PACKAGE and RUN_TESTS will be |
| organized into this FOLDER. See also the documentation for the |
| \fBFOLDER\fP target property. |
| .SS REPORT_UNDEFINED_PROPERTIES |
| .sp |
| If set, report any undefined properties to this file. |
| .sp |
| If this property is set to a filename then when CMake runs it will |
| report any properties or variables that were accessed but not defined |
| into the filename specified in this property. |
| .SS RULE_LAUNCH_COMPILE |
| .sp |
| Specify a launcher for compile rules. |
| .sp |
| Makefile Generators and the \fBNinja\fP generator prefix |
| compiler commands with the given launcher command line. |
| This is intended to allow launchers to intercept build problems |
| with high granularity. Other generators ignore this property |
| because their underlying build systems provide no hook to wrap |
| individual commands with a launcher. |
| .SS RULE_LAUNCH_CUSTOM |
| .sp |
| Specify a launcher for custom rules. |
| .sp |
| Makefile Generators and the \fBNinja\fP generator prefix |
| custom commands with the given launcher command line. |
| This is intended to allow launchers to intercept build problems |
| with high granularity. Other generators ignore this property |
| because their underlying build systems provide no hook to wrap |
| individual commands with a launcher. |
| .SS RULE_LAUNCH_LINK |
| .sp |
| Specify a launcher for link rules. |
| .sp |
| Makefile Generators and the \fBNinja\fP generator prefix |
| link and archive commands with the given launcher command line. |
| This is intended to allow launchers to intercept build problems |
| with high granularity. Other generators ignore this property |
| because their underlying build systems provide no hook to wrap |
| individual commands with a launcher. |
| .SS RULE_MESSAGES |
| .sp |
| Specify whether to report a message for each make rule. |
| .sp |
| This property specifies whether Makefile generators should add a |
| progress message describing what each build rule does. If the |
| property is not set the default is ON. Set the property to OFF to |
| disable granular messages and report only as each target completes. |
| This is intended to allow scripted builds to avoid the build time cost |
| of detailed reports. If a \fBCMAKE_RULE_MESSAGES\fP cache entry exists |
| its value initializes the value of this property. Non\-Makefile |
| generators currently ignore this property. |
| .SS TARGET_ARCHIVES_MAY_BE_SHARED_LIBS |
| .sp |
| Set if shared libraries may be named like archives. |
| .sp |
| On AIX shared libraries may be named "lib<name>.a". This property is |
| set to true on such platforms. |
| .SS TARGET_MESSAGES |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Specify whether to report the completion of each target. |
| .sp |
| This property specifies whether Makefile Generators should |
| add a progress message describing that each target has been completed. |
| If the property is not set the default is \fBON\fP\&. Set the property |
| to \fBOFF\fP to disable target completion messages. |
| .sp |
| This option is intended to reduce build output when little or no |
| work needs to be done to bring the build tree up to date. |
| .sp |
| If a \fBCMAKE_TARGET_MESSAGES\fP cache entry exists its value |
| initializes the value of this property. |
| .sp |
| Non\-Makefile generators currently ignore this property. |
| .sp |
| See the counterpart property \fBRULE_MESSAGES\fP to disable |
| everything except for target completion messages. |
| .SS TARGET_SUPPORTS_SHARED_LIBS |
| .sp |
| Does the target platform support shared libraries. |
| .sp |
| TARGET_SUPPORTS_SHARED_LIBS is a boolean specifying whether the target |
| platform supports shared libraries. Basically all current general |
| general purpose OS do so, the exception are usually embedded systems |
| with no or special OSs. |
| .SS USE_FOLDERS |
| .sp |
| Use the \fBFOLDER\fP target property to organize targets into |
| folders. |
| .sp |
| If not set, CMake treats this property as \fBOFF\fP by default. CMake |
| generators that are capable of organizing into a hierarchy of folders |
| use the values of the \fBFOLDER\fP target property to name those |
| folders. See also the documentation for the \fBFOLDER\fP target property. |
| .SS XCODE_EMIT_EFFECTIVE_PLATFORM_NAME |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Control emission of \fBEFFECTIVE_PLATFORM_NAME\fP by the \fBXcode\fP |
| generator. |
| .sp |
| It is required for building the same target with multiple SDKs. A |
| common use case is the parallel use of \fBiphoneos\fP and |
| \fBiphonesimulator\fP SDKs. |
| .sp |
| Three different states possible that control when the \fBXcode\fP |
| generator emits the \fBEFFECTIVE_PLATFORM_NAME\fP variable: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| If set to \fBON\fP it will always be emitted |
| .IP \(bu 2 |
| If set to \fBOFF\fP it will never be emitted |
| .IP \(bu 2 |
| If unset (the default) it will only be emitted when the project was |
| configured for an embedded Xcode SDK like iOS, tvOS, watchOS or any |
| of the simulators. |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| When this behavior is enable for generated Xcode projects, the |
| \fBEFFECTIVE_PLATFORM_NAME\fP variable will leak into |
| \fBGenerator expressions\fP |
| like \fBTARGET_FILE\fP and will render those mostly unusable. |
| .UNINDENT |
| .UNINDENT |
| .SH PROPERTIES ON DIRECTORIES |
| .SS ADDITIONAL_CLEAN_FILES |
| .sp |
| New in version 3.15. |
| |
| .sp |
| A ;\-list of files or directories that will be |
| removed as a part of the global \fBclean\fP target. It is useful for |
| specifying generated files or directories that are used by multiple targets |
| or by CMake itself, or that are generated in ways which cannot be captured as |
| outputs or byproducts of custom commands. |
| .sp |
| If an additional clean file is specific to a single target only, then the |
| \fBADDITIONAL_CLEAN_FILES\fP target property would usually be a better |
| choice than this directory property. |
| .sp |
| Relative paths are allowed and are interpreted relative to the |
| current binary directory. |
| .sp |
| Contents of \fBADDITIONAL_CLEAN_FILES\fP may use |
| \fBgenerator expressions\fP\&. |
| .sp |
| This property only works for the \fBNinja\fP and the Makefile |
| generators. It is ignored by other generators. |
| .SS BINARY_DIR |
| .sp |
| New in version 3.7. |
| |
| .sp |
| This read\-only directory property reports absolute path to the binary |
| directory corresponding to the source on which it is read. |
| .SS BUILDSYSTEM_TARGETS |
| .sp |
| New in version 3.7. |
| |
| .sp |
| This read\-only directory property contains a |
| semicolon\-separated list of buildsystem targets added in the |
| directory by calls to the \fBadd_library()\fP, \fBadd_executable()\fP, |
| and \fBadd_custom_target()\fP commands. The list does not include any |
| Imported Targets or Alias Targets, but does include |
| Interface Libraries\&. Each entry in the list is the logical name |
| of a target, suitable to pass to the \fBget_property()\fP command |
| \fBTARGET\fP option. |
| .sp |
| See also the \fBIMPORTED_TARGETS\fP directory property. |
| .SS CACHE_VARIABLES |
| .sp |
| List of cache variables available in the current directory. |
| .sp |
| This read\-only property specifies the list of CMake cache variables |
| currently defined. It is intended for debugging purposes. |
| .SS CLEAN_NO_CUSTOM |
| .sp |
| Set to true to tell Makefile Generators not to remove the outputs of |
| custom commands for this directory during the \fBmake clean\fP operation. |
| This is ignored on other generators because it is not possible to implement. |
| .SS CMAKE_CONFIGURE_DEPENDS |
| .sp |
| Tell CMake about additional input files to the configuration process. |
| If any named file is modified the build system will re\-run CMake to |
| re\-configure the file and generate the build system again. |
| .sp |
| Specify files as a semicolon\-separated list of paths. Relative paths |
| are interpreted as relative to the current source directory. |
| .SS COMPILE_DEFINITIONS |
| .sp |
| Preprocessor definitions for compiling a directory\(aqs sources. |
| .sp |
| This property specifies the list of options given so far to the |
| \fBadd_compile_definitions()\fP (or \fBadd_definitions()\fP) command. |
| .sp |
| The \fBCOMPILE_DEFINITIONS\fP property may be set to a semicolon\-separated |
| list of preprocessor definitions using the syntax \fBVAR\fP or \fBVAR=value\fP\&. |
| Function\-style definitions are not supported. CMake will |
| automatically escape the value correctly for the native build system |
| (note that CMake language syntax may require escapes to specify some |
| values). |
| .sp |
| This property will be initialized in each directory by its value in the |
| directory\(aqs parent. |
| .sp |
| CMake will automatically drop some definitions that are not supported |
| by the native build tool. |
| .sp |
| Disclaimer: Most native build tools have poor support for escaping |
| certain values. CMake has work\-arounds for many cases but some values |
| may just not be possible to pass correctly. If a value does not seem |
| to be escaped correctly, do not attempt to work\-around the problem by |
| adding escape sequences to the value. Your work\-around may break in a |
| future version of CMake that has improved escape support. Instead |
| consider defining the macro in a (configured) header file. Then |
| report the limitation. Known limitations include: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # \- broken almost everywhere |
| ; \- broken in VS IDE 7.0 and Borland Makefiles |
| , \- broken in VS IDE |
| % \- broken in some cases in NMake |
| & | \- broken in some cases on MinGW |
| ^ < > \e" \- broken in most Make tools on Windows |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| CMake does not reject these values outright because they do work in |
| some cases. Use with caution. |
| .sp |
| Contents of \fBCOMPILE_DEFINITIONS\fP may use "generator expressions" with |
| the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .sp |
| The corresponding \fBCOMPILE_DEFINITIONS_<CONFIG>\fP property may |
| be set to specify per\-configuration definitions. Generator expressions |
| should be preferred instead of setting the alternative property. |
| .SS COMPILE_OPTIONS |
| .sp |
| List of options to pass to the compiler. |
| .sp |
| This property holds a semicolon\-separated list of options |
| given so far to the \fBadd_compile_options()\fP command. |
| .sp |
| This property is used to initialize the \fBCOMPILE_OPTIONS\fP target |
| property when a target is created, which is used by the generators to set |
| the options for the compiler. |
| .sp |
| Contents of \fBCOMPILE_OPTIONS\fP may use "generator expressions" with the |
| syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP manual |
| for available expressions. See the \fBcmake\-buildsystem(7)\fP manual |
| for more on defining buildsystem properties. |
| .SS DEFINITIONS |
| .sp |
| For CMake 2.4 compatibility only. Use \fBCOMPILE_DEFINITIONS\fP |
| instead. |
| .sp |
| This read\-only property specifies the list of flags given so far to |
| the \fBadd_definitions()\fP command. It is intended for debugging |
| purposes. Use the \fBCOMPILE_DEFINITIONS\fP directory property |
| instead. |
| .sp |
| This built\-in read\-only property does not exist if policy |
| \fBCMP0059\fP is set to \fBNEW\fP\&. |
| .SS EXCLUDE_FROM_ALL |
| .sp |
| Set this directory property to a true value on a subdirectory to exclude |
| its targets from the "all" target of its ancestors. If excluded, running |
| e.g. \fBmake\fP in the parent directory will not build targets the |
| subdirectory by default. This does not affect the "all" target of the |
| subdirectory itself. Running e.g. \fBmake\fP inside the subdirectory will |
| still build its targets. |
| .sp |
| If the \fBEXCLUDE_FROM_ALL\fP target property is set on a target |
| then its value determines whether the target is included in the "all" |
| target of this directory and its ancestors. |
| .SS IMPLICIT_DEPENDS_INCLUDE_TRANSFORM |
| .sp |
| Specify \fB#include\fP line transforms for dependencies in a directory. |
| .sp |
| This property specifies rules to transform macro\-like \fB#include\fP lines |
| during implicit dependency scanning of C and C++ source files. The |
| list of rules must be semicolon\-separated with each entry of the form |
| \fBA_MACRO(%)=value\-with\-%\fP (the \fB%\fP must be literal). During dependency |
| scanning occurrences of \fBA_MACRO(...)\fP on \fB#include\fP lines will be |
| replaced by the value given with the macro argument substituted for |
| \fB%\fP\&. For example, the entry |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| MYDIR(%)=<mydir/%> |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| will convert lines of the form |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #include MYDIR(myheader.h) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| to |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #include <mydir/myheader.h> |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| allowing the dependency to be followed. |
| .sp |
| This property applies to sources in all targets within a directory. |
| The property value is initialized in each directory by its value in |
| the directory\(aqs parent. |
| .SS IMPORTED_TARGETS |
| .sp |
| New in version 3.21. |
| |
| .sp |
| This read\-only directory property contains a |
| semicolon\-separated list of |
| Imported Targets added in the directory by calls to the |
| \fBadd_library()\fP and \fBadd_executable()\fP commands. |
| Each entry in the list is the logical name of a target, suitable |
| to pass to the \fBget_property()\fP command \fBTARGET\fP option |
| when called in the same directory. |
| .sp |
| See also the \fBBUILDSYSTEM_TARGETS\fP directory property. |
| .SS INCLUDE_DIRECTORIES |
| .sp |
| List of preprocessor include file search directories. |
| .sp |
| This property specifies the list of directories given so far to the |
| \fBinclude_directories()\fP command. |
| .sp |
| This property is used to populate the \fBINCLUDE_DIRECTORIES\fP |
| target property, which is used by the generators to set the include |
| directories for the compiler. |
| .sp |
| In addition to accepting values from that command, values may be set |
| directly on any directory using the \fBset_property()\fP command, and can be |
| set on the current directory using the \fBset_directory_properties()\fP |
| command. A directory gets its initial value from its parent directory if it has |
| one. The initial value of the \fBINCLUDE_DIRECTORIES\fP target property |
| comes from the value of this property. Both directory and target property |
| values are adjusted by calls to the \fBinclude_directories()\fP command. |
| Calls to \fBset_property()\fP or \fBset_directory_properties()\fP, |
| however, will update the directory property value without updating target |
| property values. Therefore direct property updates must be made before |
| calls to \fBadd_executable()\fP or \fBadd_library()\fP for targets |
| they are meant to affect. |
| .sp |
| The target property values are used by the generators to set the |
| include paths for the compiler. |
| .sp |
| Contents of \fBINCLUDE_DIRECTORIES\fP may use "generator expressions" with |
| the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .SS INCLUDE_REGULAR_EXPRESSION |
| .sp |
| Include file scanning regular expression. |
| .sp |
| This property specifies the regular expression used during |
| dependency scanning to match include files that should be followed. |
| See the \fBinclude_regular_expression()\fP command for a high\-level |
| interface to set this property. |
| .SS INTERPROCEDURAL_OPTIMIZATION |
| .sp |
| Enable interprocedural optimization for targets in a directory. |
| .sp |
| If set to true, enables interprocedural optimizations if they are |
| known to be supported by the compiler. |
| .SS INTERPROCEDURAL_OPTIMIZATION_<CONFIG> |
| .sp |
| Per\-configuration interprocedural optimization for a directory. |
| .sp |
| This is a per\-configuration version of \fBINTERPROCEDURAL_OPTIMIZATION\fP\&. |
| If set, this property overrides the generic property for the named |
| configuration. |
| .SS LABELS |
| .sp |
| New in version 3.10. |
| |
| .sp |
| Specify a list of text labels associated with a directory and all of its |
| subdirectories. This is equivalent to setting the \fBLABELS\fP target |
| property and the \fBLABELS\fP test property on all targets and tests in |
| the current directory and subdirectories. Note: Launchers must enabled to |
| propagate labels to targets. |
| .sp |
| The \fBCMAKE_DIRECTORY_LABELS\fP variable can be used to initialize this |
| property. |
| .sp |
| The list is reported in dashboard submissions. |
| .SS LINK_DIRECTORIES |
| .sp |
| List of linker search directories. |
| .sp |
| This property holds a semicolon\-separated list of directories |
| and is typically populated using the \fBlink_directories()\fP command. |
| It gets its initial value from its parent directory, if it has one. |
| .sp |
| The directory property is used to initialize the \fBLINK_DIRECTORIES\fP |
| target property when a target is created. That target property is used |
| by the generators to set the library search directories for the linker. |
| .sp |
| Contents of \fBLINK_DIRECTORIES\fP may use "generator expressions" with |
| the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .SS LINK_OPTIONS |
| .sp |
| New in version 3.13. |
| |
| .sp |
| List of options to use for the link step of shared library, module |
| and executable targets as well as the device link step. |
| .sp |
| This property holds a semicolon\-separated list of options |
| given so far to the \fBadd_link_options()\fP command. |
| .sp |
| This property is used to initialize the \fBLINK_OPTIONS\fP target |
| property when a target is created, which is used by the generators to set |
| the options for the compiler. |
| .sp |
| Contents of \fBLINK_OPTIONS\fP may use "generator expressions" with the |
| syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP manual |
| for available expressions. See the \fBcmake\-buildsystem(7)\fP manual |
| for more on defining buildsystem properties. |
| .SS LISTFILE_STACK |
| .sp |
| The current stack of listfiles being processed. |
| .sp |
| This property is mainly useful when trying to debug errors in your |
| CMake scripts. It returns a list of what list files are currently |
| being processed, in order. So if one listfile does an |
| \fBinclude()\fP command then that is effectively pushing the |
| included listfile onto the stack. |
| .SS MACROS |
| .sp |
| List of macro commands available in the current directory. |
| .sp |
| This read\-only property specifies the list of CMake macros currently |
| defined. It is intended for debugging purposes. See the \fBmacro()\fP |
| command. |
| .SS PARENT_DIRECTORY |
| .sp |
| Source directory that added current subdirectory. |
| .sp |
| This read\-only property specifies the source directory that added the |
| current source directory as a subdirectory of the build. In the |
| top\-level directory the value is the empty\-string. |
| .SS RULE_LAUNCH_COMPILE |
| .sp |
| Specify a launcher for compile rules. |
| .sp |
| See the global property of the same name for details. This overrides |
| the global property for a directory. |
| .SS RULE_LAUNCH_CUSTOM |
| .sp |
| Specify a launcher for custom rules. |
| .sp |
| See the global property of the same name for details. This overrides |
| the global property for a directory. |
| .SS RULE_LAUNCH_LINK |
| .sp |
| Specify a launcher for link rules. |
| .sp |
| See the global property of the same name for details. This overrides |
| the global property for a directory. |
| .SS SOURCE_DIR |
| .sp |
| New in version 3.7. |
| |
| .sp |
| This read\-only directory property reports absolute path to the source |
| directory on which it is read. |
| .SS SUBDIRECTORIES |
| .sp |
| New in version 3.7. |
| |
| .sp |
| This read\-only directory property contains a |
| semicolon\-separated list of subdirectories processed so far by |
| the \fBadd_subdirectory()\fP or \fBsubdirs()\fP commands. Each entry is |
| the absolute path to the source directory (containing the \fBCMakeLists.txt\fP |
| file). This is suitable to pass to the \fBget_property()\fP command |
| \fBDIRECTORY\fP option. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The \fBsubdirs()\fP command does not process its arguments until |
| after the calling directory is fully processed. Therefore looking |
| up this property in the current directory will not see them. |
| .UNINDENT |
| .UNINDENT |
| .SS TESTS |
| .sp |
| New in version 3.12. |
| |
| .sp |
| List of tests. |
| .sp |
| This read\-only property holds a |
| semicolon\-separated list of tests |
| defined so far, in the current directory, by the \fBadd_test()\fP command. |
| .SS TEST_INCLUDE_FILES |
| .sp |
| New in version 3.10. |
| |
| .sp |
| A list of cmake files that will be included when ctest is run. |
| .sp |
| If you specify \fBTEST_INCLUDE_FILES\fP, those files will be included and |
| processed when ctest is run on the directory. |
| .SS VARIABLES |
| .sp |
| List of variables defined in the current directory. |
| .sp |
| This read\-only property specifies the list of CMake variables |
| currently defined. It is intended for debugging purposes. |
| .SS VS_GLOBAL_SECTION_POST_<section> |
| .sp |
| Specify a postSolution global section in Visual Studio. |
| .sp |
| Setting a property like this generates an entry of the following form |
| in the solution file: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| GlobalSection(<section>) = postSolution |
| <contents based on property value> |
| EndGlobalSection |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The property must be set to a semicolon\-separated list of \fBkey=value\fP |
| pairs. Each such pair will be transformed into an entry in the |
| solution global section. Whitespace around key and value is ignored. |
| List elements which do not contain an equal sign are skipped. |
| .sp |
| This property only works for Visual Studio 9 and above; it is ignored |
| on other generators. The property only applies when set on a |
| directory whose \fBCMakeLists.txt\fP contains a \fBproject()\fP command. |
| .sp |
| Note that CMake generates postSolution sections \fBExtensibilityGlobals\fP |
| and \fBExtensibilityAddIns\fP by default. If you set the corresponding |
| property, it will override the default section. For example, setting |
| \fBVS_GLOBAL_SECTION_POST_ExtensibilityGlobals\fP will override the default |
| contents of the \fBExtensibilityGlobals\fP section, while keeping |
| ExtensibilityAddIns on its default. However, CMake will always |
| add a \fBSolutionGuid\fP to the \fBExtensibilityGlobals\fP section |
| if it is not specified explicitly. |
| .SS VS_GLOBAL_SECTION_PRE_<section> |
| .sp |
| Specify a preSolution global section in Visual Studio. |
| .sp |
| Setting a property like this generates an entry of the following form |
| in the solution file: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| GlobalSection(<section>) = preSolution |
| <contents based on property value> |
| EndGlobalSection |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The property must be set to a semicolon\-separated list of \fBkey=value\fP |
| pairs. Each such pair will be transformed into an entry in the |
| solution global section. Whitespace around key and value is ignored. |
| List elements which do not contain an equal sign are skipped. |
| .sp |
| This property only works for Visual Studio 9 and above; it is ignored |
| on other generators. The property only applies when set on a |
| directory whose \fBCMakeLists.txt\fP contains a \fBproject()\fP command. |
| .SS VS_STARTUP_PROJECT |
| .sp |
| New in version 3.6. |
| |
| .sp |
| Specify the default startup project in a Visual Studio solution. |
| .sp |
| The Visual Studio Generators create a \fB\&.sln\fP file for each directory |
| whose \fBCMakeLists.txt\fP file calls the \fBproject()\fP command. Set this |
| property in the same directory as a \fBproject()\fP command call (e.g. in |
| the top\-level \fBCMakeLists.txt\fP file) to specify the default startup project |
| for the corresponding solution file. |
| .sp |
| The property must be set to the name of an existing target. This |
| will cause that project to be listed first in the generated solution |
| file causing Visual Studio to make it the startup project if the |
| solution has never been opened before. |
| .sp |
| If this property is not specified, then the \fBALL_BUILD\fP project |
| will be the default. |
| .SH PROPERTIES ON TARGETS |
| .SS ADDITIONAL_CLEAN_FILES |
| .sp |
| New in version 3.15. |
| |
| .sp |
| A ;\-list of files or directories that will be |
| removed as a part of the global \fBclean\fP target. It can be used to specify |
| files and directories that are generated as part of building the target or |
| that are directly associated with the target in some way (e.g. created as a |
| result of running the target). |
| .sp |
| For custom targets, if such files can be captured as outputs or byproducts |
| instead, then that should be preferred over adding them to this property. |
| If an additional clean file is used by multiple targets or isn\(aqt |
| target\-specific, then the \fBADDITIONAL_CLEAN_FILES\fP directory |
| property may be the more appropriate property to use. |
| .sp |
| Relative paths are allowed and are interpreted relative to the |
| current binary directory. |
| .sp |
| Contents of \fBADDITIONAL_CLEAN_FILES\fP may use |
| \fBgenerator expressions\fP\&. |
| .sp |
| This property only works for the \fBNinja\fP and the Makefile |
| generators. It is ignored by other generators. |
| .SS AIX_EXPORT_ALL_SYMBOLS |
| .sp |
| New in version 3.17. |
| |
| .sp |
| On AIX, CMake automatically exports all symbols from shared libraries, and |
| from executables with the \fBENABLE_EXPORTS\fP target property set. |
| Explicitly disable this boolean property to suppress the behavior and |
| export no symbols by default. In this case it is expected that the project |
| will use other means to export some symbols. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_AIX_EXPORT_ALL_SYMBOLS\fP variable if it is set |
| when a target is created. |
| .SS ALIAS_GLOBAL |
| .sp |
| New in version 3.18. |
| |
| .sp |
| Read\-only property indicating of whether an ALIAS target |
| is globally visible. |
| .sp |
| The boolean value of this property is \fBTRUE\fP for aliases to |
| IMPORTED targets created |
| with the \fBGLOBAL\fP options to \fBadd_executable()\fP or |
| \fBadd_library()\fP, \fBFALSE\fP otherwise. It is undefined for |
| targets built within the project. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Promoting an IMPORTED target from \fBLOCAL\fP |
| to \fBGLOBAL\fP scope by changing the value or \fBIMPORTED_GLOBAL\fP |
| target property do not change the scope of local aliases. |
| .UNINDENT |
| .UNINDENT |
| .SS ALIASED_TARGET |
| .sp |
| Name of target aliased by this target. |
| .sp |
| If this is an Alias Target, this property contains |
| the name of the target aliased. |
| .SS ANDROID_ANT_ADDITIONAL_OPTIONS |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Set the additional options for Android Ant build system. This is |
| a string value containing all command line options for the Ant build. |
| This property is initialized by the value of the |
| \fBCMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS\fP variable if it is |
| set when a target is created. |
| .SS ANDROID_API |
| .sp |
| New in version 3.1. |
| |
| .sp |
| When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio |
| Edition, this property sets the Android target API version (e.g. \fB15\fP). |
| The version number must be a positive decimal integer. This property is |
| initialized by the value of the \fBCMAKE_ANDROID_API\fP variable if |
| it is set when a target is created. |
| .SS ANDROID_API_MIN |
| .sp |
| New in version 3.2. |
| |
| .sp |
| Set the Android MIN API version (e.g. \fB9\fP). The version number |
| must be a positive decimal integer. This property is initialized by |
| the value of the \fBCMAKE_ANDROID_API_MIN\fP variable if it is set |
| when a target is created. Native code builds using this API version. |
| .SS ANDROID_ARCH |
| .sp |
| New in version 3.4. |
| |
| .sp |
| When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio |
| Edition, this property sets the Android target architecture. |
| .sp |
| This is a string property that could be set to the one of |
| the following values: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBarmv7\-a\fP: "ARMv7\-A (armv7\-a)" |
| .IP \(bu 2 |
| \fBarmv7\-a\-hard\fP: "ARMv7\-A, hard\-float ABI (armv7\-a)" |
| .IP \(bu 2 |
| \fBarm64\-v8a\fP: "ARMv8\-A, 64bit (arm64\-v8a)" |
| .IP \(bu 2 |
| \fBx86\fP: "x86 (x86)" |
| .IP \(bu 2 |
| \fBx86_64\fP: "x86_64 (x86_64)" |
| .UNINDENT |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_ANDROID_ARCH\fP variable if it is set |
| when a target is created. |
| .SS ANDROID_ASSETS_DIRECTORIES |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Set the Android assets directories to copy into the main assets |
| folder before build. This a string property that contains the |
| directory paths separated by semicolon. |
| This property is initialized by the value of the |
| \fBCMAKE_ANDROID_ASSETS_DIRECTORIES\fP variable if it is set when |
| a target is created. |
| .SS ANDROID_GUI |
| .sp |
| New in version 3.1. |
| |
| .sp |
| When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio |
| Edition, this property specifies whether to build an executable as an |
| application package on Android. |
| .sp |
| When this property is set to true the executable when built for Android |
| will be created as an application package. This property is initialized |
| by the value of the \fBCMAKE_ANDROID_GUI\fP variable if it is set |
| when a target is created. |
| .sp |
| Add the \fBAndroidManifest.xml\fP source file explicitly to the |
| target \fBadd_executable()\fP command invocation to specify the |
| root directory of the application package source. |
| .SS ANDROID_JAR_DEPENDENCIES |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Set the Android property that specifies JAR dependencies. |
| This is a string value property. This property is initialized |
| by the value of the \fBCMAKE_ANDROID_JAR_DEPENDENCIES\fP |
| variable if it is set when a target is created. |
| .SS ANDROID_JAR_DIRECTORIES |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Set the Android property that specifies directories to search for |
| the JAR libraries. |
| .sp |
| This a string property that contains the directory paths separated by |
| semicolons. This property is initialized by the value of the |
| \fBCMAKE_ANDROID_JAR_DIRECTORIES\fP variable if it is set when |
| a target is created. |
| .sp |
| Contents of \fBANDROID_JAR_DIRECTORIES\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. |
| .SS ANDROID_JAVA_SOURCE_DIR |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Set the Android property that defines the Java source code root directories. |
| This a string property that contains the directory paths separated by semicolon. |
| This property is initialized by the value of the |
| \fBCMAKE_ANDROID_JAVA_SOURCE_DIR\fP variable if it is set |
| when a target is created. |
| .SS ANDROID_NATIVE_LIB_DEPENDENCIES |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Set the Android property that specifies the .so dependencies. |
| This is a string property. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES\fP variable if it is set |
| when a target is created. |
| .sp |
| Contents of \fBANDROID_NATIVE_LIB_DEPENDENCIES\fP may use |
| "generator expressions" with the syntax \fB$<...>\fP\&. See the |
| \fBcmake\-generator\-expressions(7)\fP manual for |
| available expressions. |
| .SS ANDROID_NATIVE_LIB_DIRECTORIES |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Set the Android property that specifies directories to search for the \fB\&.so\fP |
| libraries. |
| .sp |
| This a string property that contains the directory paths separated |
| by semicolons. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_ANDROID_NATIVE_LIB_DIRECTORIES\fP variable if it is set when a |
| target is created. |
| .sp |
| Contents of \fBANDROID_NATIVE_LIB_DIRECTORIES\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. |
| .SS ANDROID_PROCESS_MAX |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Set the Android property that defines the maximum number of a |
| parallel Android NDK compiler processes (e.g. \fB4\fP). |
| This property is initialized by the value of the |
| \fBCMAKE_ANDROID_PROCESS_MAX\fP variable if it is set |
| when a target is created. |
| .SS ANDROID_PROGUARD |
| .sp |
| New in version 3.4. |
| |
| .sp |
| When this property is set to true that enables the ProGuard tool to shrink, |
| optimize, and obfuscate the code by removing unused code and renaming |
| classes, fields, and methods with semantically obscure names. |
| This property is initialized by the value of the |
| \fBCMAKE_ANDROID_PROGUARD\fP variable if it is set |
| when a target is created. |
| .SS ANDROID_PROGUARD_CONFIG_PATH |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Set the Android property that specifies the location of the ProGuard |
| config file. Leave empty to use the default one. |
| This a string property that contains the path to ProGuard config file. |
| This property is initialized by the value of the |
| \fBCMAKE_ANDROID_PROGUARD_CONFIG_PATH\fP variable if it is set |
| when a target is created. |
| .SS ANDROID_SECURE_PROPS_PATH |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Set the Android property that states the location of the secure properties file. |
| This is a string property that contains the file path. |
| This property is initialized by the value of the |
| \fBCMAKE_ANDROID_SECURE_PROPS_PATH\fP variable |
| if it is set when a target is created. |
| .SS ANDROID_SKIP_ANT_STEP |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Set the Android property that defines whether or not to skip the Ant build step. |
| This is a boolean property initialized by the value of the |
| \fBCMAKE_ANDROID_SKIP_ANT_STEP\fP variable if it is set when a target is created. |
| .SS ANDROID_STL_TYPE |
| .sp |
| New in version 3.4. |
| |
| .sp |
| When Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio |
| Edition, this property specifies the type of STL support for the project. |
| This is a string property that could set to the one of the following values: |
| .INDENT 0.0 |
| .TP |
| .B \fBnone\fP |
| No C++ Support |
| .TP |
| .B \fBsystem\fP |
| Minimal C++ without STL |
| .TP |
| .B \fBgabi++_static\fP |
| GAbi++ Static |
| .TP |
| .B \fBgabi++_shared\fP |
| GAbi++ Shared |
| .TP |
| .B \fBgnustl_static\fP |
| GNU libstdc++ Static |
| .TP |
| .B \fBgnustl_shared\fP |
| GNU libstdc++ Shared |
| .TP |
| .B \fBstlport_static\fP |
| STLport Static |
| .TP |
| .B \fBstlport_shared\fP |
| STLport Shared |
| .UNINDENT |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_ANDROID_STL_TYPE\fP variable if it is set when a target is |
| created. |
| .SS ARCHIVE_OUTPUT_DIRECTORY |
| .sp |
| Output directory in which to build ARCHIVE target files. |
| .sp |
| This property specifies the directory into which archive target files |
| should be built. The property value may use |
| \fBgenerator expressions\fP\&. |
| Multi\-configuration generators (Visual Studio, |
| \fBXcode\fP, \fBNinja Multi\-Config\fP) append a |
| per\-configuration subdirectory to the specified directory unless a generator |
| expression is used. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_ARCHIVE_OUTPUT_DIRECTORY\fP variable if it is set when a target is created. |
| .sp |
| See also the \fBARCHIVE_OUTPUT_DIRECTORY_<CONFIG>\fP target property. |
| .SS ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> |
| .sp |
| Per\-configuration output directory for |
| ARCHIVE target files. |
| .sp |
| This is a per\-configuration version of the |
| \fBARCHIVE_OUTPUT_DIRECTORY\fP target property, but |
| multi\-configuration generators (VS, Xcode) do NOT append a |
| per\-configuration subdirectory to the specified directory. This |
| property is initialized by the value of the |
| \fBCMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>\fP variable if |
| it is set when a target is created. |
| .sp |
| Contents of \fBARCHIVE_OUTPUT_DIRECTORY_<CONFIG>\fP may use |
| \fBgenerator expressions\fP\&. |
| .SS ARCHIVE_OUTPUT_NAME |
| .sp |
| Output name for ARCHIVE target files. |
| .sp |
| This property specifies the base name for archive target files. It |
| overrides \fBOUTPUT_NAME\fP and \fBOUTPUT_NAME_<CONFIG>\fP |
| properties. |
| .sp |
| See also the \fBARCHIVE_OUTPUT_NAME_<CONFIG>\fP target property. |
| .SS ARCHIVE_OUTPUT_NAME_<CONFIG> |
| .sp |
| Per\-configuration output name for |
| ARCHIVE target files. |
| .sp |
| This is the configuration\-specific version of the |
| \fBARCHIVE_OUTPUT_NAME\fP target property. |
| .SS AUTOGEN_BUILD_DIR |
| .sp |
| New in version 3.9. |
| |
| .sp |
| Directory where \fBAUTOMOC\fP, \fBAUTOUIC\fP and \fBAUTORCC\fP |
| generate files for the target. |
| .sp |
| The directory is created on demand and automatically added to the |
| \fBADDITIONAL_CLEAN_FILES\fP target property. |
| .sp |
| When unset or empty the directory \fB<dir>/<target\-name>_autogen\fP is used where |
| \fB<dir>\fP is \fBCMAKE_CURRENT_BINARY_DIR\fP and \fB<target\-name>\fP |
| is \fBNAME\fP\&. |
| .sp |
| By default \fI\%AUTOGEN_BUILD_DIR\fP is unset. |
| .sp |
| See the \fBcmake\-qt(7)\fP manual for more information on using CMake |
| with Qt. |
| .SS AUTOGEN_ORIGIN_DEPENDS |
| .sp |
| New in version 3.14. |
| |
| .sp |
| Switch for forwarding origin target dependencies to the corresponding |
| \fB_autogen\fP target. |
| .sp |
| Targets which have their \fBAUTOMOC\fP or \fBAUTOUIC\fP property |
| \fBON\fP have a corresponding \fB_autogen\fP target which generates |
| \fBmoc\fP and \fBuic\fP files. As this \fB_autogen\fP target is created at |
| generate\-time, it is not possible to define dependencies of it using |
| e.g. \fBadd_dependencies()\fP\&. Instead the |
| \fI\%AUTOGEN_ORIGIN_DEPENDS\fP target property decides whether the origin |
| target dependencies should be forwarded to the \fB_autogen\fP target or not. |
| .sp |
| By default \fI\%AUTOGEN_ORIGIN_DEPENDS\fP is initialized from |
| \fBCMAKE_AUTOGEN_ORIGIN_DEPENDS\fP which is \fBON\fP by default. |
| .sp |
| In total the dependencies of the \fB_autogen\fP target are composed from |
| .INDENT 0.0 |
| .IP \(bu 2 |
| forwarded origin target dependencies |
| (enabled by default via \fI\%AUTOGEN_ORIGIN_DEPENDS\fP) |
| .IP \(bu 2 |
| additional user defined dependencies from \fBAUTOGEN_TARGET_DEPENDS\fP |
| .UNINDENT |
| .sp |
| See the \fBcmake\-qt(7)\fP manual for more information on using CMake |
| with Qt. |
| .SS Note |
| .sp |
| Disabling \fI\%AUTOGEN_ORIGIN_DEPENDS\fP is useful to avoid building of |
| origin target dependencies when building the \fB_autogen\fP target only. |
| This is especially interesting when a |
| \fBglobal autogen target\fP is enabled. |
| .sp |
| When the \fB_autogen\fP target doesn\(aqt require all the origin target\(aqs |
| dependencies, and \fI\%AUTOGEN_ORIGIN_DEPENDS\fP is disabled, it might be |
| necessary to extend \fBAUTOGEN_TARGET_DEPENDS\fP to add missing |
| dependencies. |
| .SS AUTOGEN_PARALLEL |
| .sp |
| New in version 3.11. |
| |
| .sp |
| Number of parallel \fBmoc\fP or \fBuic\fP processes to start when using |
| \fBAUTOMOC\fP and \fBAUTOUIC\fP\&. |
| .sp |
| The custom \fB<origin>_autogen\fP target starts a number of threads of which |
| each one parses a source file and on demand starts a \fBmoc\fP or \fBuic\fP |
| process. \fBAUTOGEN_PARALLEL\fP controls how many parallel threads |
| (and therefore \fBmoc\fP or \fBuic\fP processes) are started. |
| .INDENT 0.0 |
| .IP \(bu 2 |
| An empty (or unset) value or the string \fBAUTO\fP sets the number of |
| threads/processes to the number of physical CPUs on the host system. |
| .IP \(bu 2 |
| A positive non zero integer value sets the exact thread/process count. |
| .IP \(bu 2 |
| Otherwise a single thread/process is started. |
| .UNINDENT |
| .sp |
| By default \fBAUTOGEN_PARALLEL\fP is initialized from |
| \fBCMAKE_AUTOGEN_PARALLEL\fP\&. |
| .sp |
| See the \fBcmake\-qt(7)\fP manual for more information on using CMake |
| with Qt. |
| .SS AUTOGEN_TARGET_DEPENDS |
| .sp |
| Additional target dependencies of the corresponding \fB_autogen\fP target. |
| .sp |
| Targets which have their \fBAUTOMOC\fP or \fBAUTOUIC\fP property |
| \fBON\fP have a corresponding \fB_autogen\fP target which generates |
| \fBmoc\fP and \fBuic\fP files. As this \fB_autogen\fP target is created at |
| generate\-time, it is not possible to define dependencies of it using |
| e.g. \fBadd_dependencies()\fP\&. Instead the |
| \fI\%AUTOGEN_TARGET_DEPENDS\fP target property can be set to a |
| ;\-list of additional dependencies for the |
| \fB_autogen\fP target. Dependencies can be target names or file names. |
| .sp |
| In total the dependencies of the \fB_autogen\fP target are composed from |
| .INDENT 0.0 |
| .IP \(bu 2 |
| forwarded origin target dependencies |
| (enabled by default via \fBAUTOGEN_ORIGIN_DEPENDS\fP) |
| .IP \(bu 2 |
| additional user defined dependencies from \fI\%AUTOGEN_TARGET_DEPENDS\fP |
| .UNINDENT |
| .sp |
| See the \fBcmake\-qt(7)\fP manual for more information on using CMake |
| with Qt. |
| .SS Use cases |
| .sp |
| If \fBAUTOMOC\fP or \fBAUTOUIC\fP depends on a file that is either |
| .INDENT 0.0 |
| .IP \(bu 2 |
| a \fBGENERATED\fP non C++ file (e.g. a \fBGENERATED\fP \fB\&.json\fP |
| or \fB\&.ui\fP file) or |
| .IP \(bu 2 |
| a \fBGENERATED\fP C++ file that isn\(aqt recognized by \fBAUTOMOC\fP |
| and \fBAUTOUIC\fP because it\(aqs skipped by \fBSKIP_AUTOMOC\fP, |
| \fBSKIP_AUTOUIC\fP, \fBSKIP_AUTOGEN\fP or \fBCMP0071\fP or |
| .IP \(bu 2 |
| a file that isn\(aqt in the origin target\(aqs sources |
| .UNINDENT |
| .sp |
| it must be added to \fI\%AUTOGEN_TARGET_DEPENDS\fP\&. |
| .SS AUTOMOC |
| .sp |
| Should the target be processed with auto\-moc (for Qt projects). |
| .sp |
| \fI\%AUTOMOC\fP is a boolean specifying whether CMake will handle the Qt |
| \fBmoc\fP preprocessor automatically, i.e. without having to use commands like |
| \fBQT4_WRAP_CPP()\fP, \fBQT5_WRAP_CPP()\fP, etc. |
| Currently, Qt versions 4 to 6 are supported. |
| .sp |
| This property is initialized by the value of the \fBCMAKE_AUTOMOC\fP |
| variable if it is set when a target is created. |
| .sp |
| When this property is set \fBON\fP, CMake will scan the header and |
| source files at build time and invoke \fBmoc\fP accordingly. |
| .SS Header file processing |
| .sp |
| At configuration time, a list of header files that should be scanned by |
| \fI\%AUTOMOC\fP is computed from the target\(aqs sources. |
| .INDENT 0.0 |
| .IP \(bu 2 |
| All header files in the target\(aqs sources are added to the scan list. |
| .IP \(bu 2 |
| For all C++ source files \fB<source_base>.<source_extension>\fP in the |
| target\(aqs sources, CMake searches for |
| .INDENT 2.0 |
| .IP \(bu 2 |
| a regular header with the same base name |
| (\fB<source_base>.<header_extention>\fP) and |
| .IP \(bu 2 |
| a private header with the same base name and a \fB_p\fP suffix |
| (\fB<source_base>_p.<header_extention>\fP) |
| .UNINDENT |
| .sp |
| and adds these to the scan list. |
| .UNINDENT |
| .sp |
| At build time, CMake scans each unknown or modified header file from the |
| list and searches for |
| .INDENT 0.0 |
| .IP \(bu 2 |
| a Qt macro from \fBAUTOMOC_MACRO_NAMES\fP, |
| .IP \(bu 2 |
| additional file dependencies from the \fBFILE\fP argument of a |
| \fBQ_PLUGIN_METADATA\fP macro and |
| .IP \(bu 2 |
| additional file dependencies detected by filters defined in |
| \fBAUTOMOC_DEPEND_FILTERS\fP\&. |
| .UNINDENT |
| .sp |
| If a Qt macro is found, then the header will be compiled by the \fBmoc\fP to the |
| output file \fBmoc_<base_name>.cpp\fP\&. The complete output file path is |
| described in the section \fI\%Output file location\fP\&. |
| .sp |
| The header will be \fBmoc\fP compiled again if a file from the additional file |
| dependencies changes. |
| .sp |
| Header \fBmoc\fP output files \fBmoc_<base_name>.cpp\fP can be included in source |
| files. In the section \fI\%Including header moc files in sources\fP there is more |
| information on that topic. |
| .SS Source file processing |
| .sp |
| At build time, CMake scans each unknown or modified C++ source file from the |
| target\(aqs sources for |
| .INDENT 0.0 |
| .IP \(bu 2 |
| a Qt macro from \fBAUTOMOC_MACRO_NAMES\fP, |
| .IP \(bu 2 |
| includes of header \fBmoc\fP files |
| (see \fI\%Including header moc files in sources\fP), |
| .IP \(bu 2 |
| additional file dependencies from the \fBFILE\fP argument of a |
| \fBQ_PLUGIN_METADATA\fP macro and |
| .IP \(bu 2 |
| additional file dependencies detected by filters defined in |
| \fBAUTOMOC_DEPEND_FILTERS\fP\&. |
| .UNINDENT |
| .sp |
| If a Qt macro is found, then the C++ source file |
| \fB<base>.<source_extension>\fP is expected to as well contain an include |
| statement |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #include <<base>.moc> // or |
| #include "<base>.moc" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The source file then will be compiled by the \fBmoc\fP to the output file |
| \fB<base>.moc\fP\&. A description of the complete output file path is in section |
| \fI\%Output file location\fP\&. |
| .sp |
| The source will be \fBmoc\fP compiled again if a file from the additional file |
| dependencies changes. |
| .SS Including header moc files in sources |
| .sp |
| A source file can include the \fBmoc\fP output file of a header |
| \fB<header_base>.<header_extension>\fP by using an include statement of |
| the form |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #include <moc_<header_base>.cpp> // or |
| #include "moc_<header_base>.cpp" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If the \fBmoc\fP output file of a header is included by a source, it will |
| be generated in a different location than if it was not included. This is |
| described in the section \fI\%Output file location\fP\&. |
| .SS Output file location |
| .SS Included moc output files |
| .sp |
| \fBmoc\fP output files that are included by a source file will be generated in |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fB<AUTOGEN_BUILD_DIR>/include\fP |
| for single configuration generators or in |
| .IP \(bu 2 |
| \fB<AUTOGEN_BUILD_DIR>/include_<CONFIG>\fP |
| for \fBmulti configuration\fP generators. |
| .UNINDENT |
| .sp |
| Where \fB<AUTOGEN_BUILD_DIR>\fP is the value of the target property |
| \fBAUTOGEN_BUILD_DIR\fP\&. |
| .sp |
| The include directory is automatically added to the target\(aqs |
| \fBINCLUDE_DIRECTORIES\fP\&. |
| .SS Not included moc output files |
| .sp |
| \fBmoc\fP output files that are not included in a source file will be generated |
| in |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fB<AUTOGEN_BUILD_DIR>/<SOURCE_DIR_CHECKSUM>\fP |
| for single configuration generators or in, |
| .IP \(bu 2 |
| \fB<AUTOGEN_BUILD_DIR>/include_<CONFIG>/<SOURCE_DIR_CHECKSUM>\fP |
| for \fBmulti configuration\fP generators. |
| .UNINDENT |
| .sp |
| Where \fB<SOURCE_DIR_CHECKSUM>\fP is a checksum computed from the relative |
| parent directory path of the \fBmoc\fP input file. This scheme allows to have |
| \fBmoc\fP input files with the same name in different directories. |
| .sp |
| All not included \fBmoc\fP output files will be included automatically by the |
| CMake generated file |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fB<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp\fP, or |
| .IP \(bu 2 |
| \fB<AUTOGEN_BUILD_DIR>/mocs_compilation_$<CONFIG>.cpp\fP, |
| .UNINDENT |
| .sp |
| which is added to the target\(aqs sources. |
| .SS Qt version detection |
| .sp |
| \fI\%AUTOMOC\fP enabled targets need to know the Qt major and minor |
| version they\(aqre working with. The major version usually is provided by the |
| \fBINTERFACE_QT_MAJOR_VERSION\fP property of the \fBQt[456]Core\fP library, |
| that the target links to. To find the minor version, CMake builds a list of |
| available Qt versions from |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBQt6Core_VERSION_MAJOR\fP and \fBQt6Core_VERSION_MINOR\fP variables |
| (usually set by \fBfind_package(Qt6...)\fP) |
| .IP \(bu 2 |
| \fBQt6Core_VERSION_MAJOR\fP and \fBQt6Core_VERSION_MINOR\fP directory properties |
| .IP \(bu 2 |
| \fBQt5Core_VERSION_MAJOR\fP and \fBQt5Core_VERSION_MINOR\fP variables |
| (usually set by \fBfind_package(Qt5...)\fP) |
| .IP \(bu 2 |
| \fBQt5Core_VERSION_MAJOR\fP and \fBQt5Core_VERSION_MINOR\fP directory properties |
| .IP \(bu 2 |
| \fBQT_VERSION_MAJOR\fP and \fBQT_VERSION_MINOR\fP variables |
| (usually set by \fBfind_package(Qt4...)\fP) |
| .IP \(bu 2 |
| \fBQT_VERSION_MAJOR\fP and \fBQT_VERSION_MINOR\fP directory properties |
| .UNINDENT |
| .sp |
| in the context of the \fBadd_executable()\fP or \fBadd_library()\fP call. |
| .sp |
| Assumed \fBINTERFACE_QT_MAJOR_VERSION\fP is a valid number, the first |
| entry in the list with a matching major version is taken. If no matching major |
| version was found, an error is generated. |
| If \fBINTERFACE_QT_MAJOR_VERSION\fP is not a valid number, the first |
| entry in the list is taken. |
| .sp |
| A \fBfind_package(Qt[456]...)\fP call sets the \fBQT/Qt[56]Core_VERSION_MAJOR/MINOR\fP |
| variables. If the call is in a different context than the |
| \fBadd_executable()\fP or \fBadd_library()\fP call, e.g. in a function, |
| then the version variables might not be available to the \fI\%AUTOMOC\fP |
| enabled target. |
| In that case the version variables can be forwarded from the |
| \fBfind_package(Qt[456]...)\fP calling context to the \fBadd_executable()\fP |
| or \fBadd_library()\fP calling context as directory properties. |
| The following Qt5 example demonstrates the procedure. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| function (add_qt5_client) |
| find_package(Qt5 REQUIRED QUIET COMPONENTS Core Widgets) |
| ... |
| set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" |
| PROPERTY Qt5Core_VERSION_MAJOR "${Qt5Core_VERSION_MAJOR}") |
| set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" |
| PROPERTY Qt5Core_VERSION_MINOR "${Qt5Core_VERSION_MAJOR}") |
| ... |
| endfunction () |
| \&... |
| add_qt5_client() |
| add_executable(myTarget main.cpp) |
| target_link_libraries(myTarget Qt5::QtWidgets) |
| set_property(TARGET myTarget PROPERTY AUTOMOC ON) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Modifiers |
| .sp |
| \fBAUTOMOC_EXECUTABLE\fP: |
| The \fBmoc\fP executable will be detected automatically, but can be forced to |
| a certain binary using this target property. |
| .sp |
| \fBAUTOMOC_MOC_OPTIONS\fP: |
| Additional command line options for \fBmoc\fP can be set in this target property. |
| .sp |
| \fBAUTOMOC_MACRO_NAMES\fP: |
| This list of Qt macro names can be extended to search for additional macros in |
| headers and sources. |
| .sp |
| \fBAUTOMOC_DEPEND_FILTERS\fP: |
| \fBmoc\fP dependency file names can be extracted from headers or sources by |
| defining file name filters in this target property. |
| .sp |
| \fBAUTOMOC_COMPILER_PREDEFINES\fP: |
| Compiler pre definitions for \fBmoc\fP are written to the \fBmoc_predefs.h\fP file. |
| The generation of this file can be enabled or disabled in this target property. |
| .sp |
| \fBSKIP_AUTOMOC\fP: |
| Sources and headers can be excluded from \fI\%AUTOMOC\fP processing by |
| setting this source file property. |
| .sp |
| \fBSKIP_AUTOGEN\fP: |
| Source files can be excluded from \fI\%AUTOMOC\fP, |
| \fBAUTOUIC\fP and \fBAUTORCC\fP processing by |
| setting this source file property. |
| .sp |
| \fBAUTOGEN_SOURCE_GROUP\fP: |
| This global property can be used to group files generated by |
| \fI\%AUTOMOC\fP or \fBAUTORCC\fP together in an IDE, e.g. in MSVS. |
| .sp |
| \fBAUTOGEN_TARGETS_FOLDER\fP: |
| This global property can be used to group \fI\%AUTOMOC\fP, |
| \fBAUTOUIC\fP and \fBAUTORCC\fP targets together in an IDE, |
| e.g. in MSVS. |
| .sp |
| \fBCMAKE_GLOBAL_AUTOGEN_TARGET\fP: |
| A global \fBautogen\fP target, that depends on all \fI\%AUTOMOC\fP or |
| \fBAUTOUIC\fP generated \fB<ORIGIN>_autogen\fP targets in the project, |
| will be generated when this variable is \fBON\fP\&. |
| .sp |
| \fBAUTOGEN_PARALLEL\fP: |
| This target property controls the number of \fBmoc\fP or \fBuic\fP processes to |
| start in parallel during builds. |
| .sp |
| See the \fBcmake\-qt(7)\fP manual for more information on using CMake |
| with Qt. |
| .SS AUTOMOC_COMPILER_PREDEFINES |
| .sp |
| New in version 3.10. |
| |
| .sp |
| Boolean value used by \fBAUTOMOC\fP to determine if the |
| compiler pre definitions file \fBmoc_predefs.h\fP should be generated. |
| .sp |
| CMake generates a \fBmoc_predefs.h\fP file with compiler pre definitions |
| from the output of the command defined in |
| \fBCMAKE_CXX_COMPILER_PREDEFINES_COMMAND\fP |
| when |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBAUTOMOC\fP is enabled, |
| .IP \(bu 2 |
| \fI\%AUTOMOC_COMPILER_PREDEFINES\fP is enabled, |
| .IP \(bu 2 |
| \fBCMAKE_CXX_COMPILER_PREDEFINES_COMMAND\fP isn\(aqt empty and |
| .IP \(bu 2 |
| the Qt version is greater or equal 5.8. |
| .UNINDENT |
| .sp |
| The \fBmoc_predefs.h\fP file, which is generated in \fBAUTOGEN_BUILD_DIR\fP, |
| is passed to \fBmoc\fP as the argument to the \fB\-\-include\fP option. |
| .sp |
| By default \fI\%AUTOMOC_COMPILER_PREDEFINES\fP is initialized from |
| \fBCMAKE_AUTOMOC_COMPILER_PREDEFINES\fP, which is ON by default. |
| .sp |
| See the \fBcmake\-qt(7)\fP manual for more information on using CMake |
| with Qt. |
| .SS AUTOMOC_DEPEND_FILTERS |
| .sp |
| New in version 3.9. |
| |
| .sp |
| Filter definitions used by \fBAUTOMOC\fP to extract file names from a |
| source file that are registered as additional dependencies for the |
| \fBmoc\fP file of the source file. |
| .sp |
| Filters are defined as \fBKEYWORD;REGULAR_EXPRESSION\fP pairs. First the file |
| content is searched for \fBKEYWORD\fP\&. If it is found at least once, then file |
| names are extracted by successively searching for \fBREGULAR_EXPRESSION\fP and |
| taking the first match group. |
| .sp |
| The file name found in the first match group is searched for |
| .INDENT 0.0 |
| .IP \(bu 2 |
| first in the vicinity of the source file |
| .IP \(bu 2 |
| and afterwards in the target\(aqs \fBINCLUDE_DIRECTORIES\fP\&. |
| .UNINDENT |
| .sp |
| If any of the extracted files changes, then the \fBmoc\fP file for the source |
| file gets rebuilt even when the source file itself doesn\(aqt change. |
| .sp |
| If any of the extracted files is \fBGENERATED\fP or if it is not in the |
| target\(aqs sources, then it might be necessary to add it to the |
| \fB_autogen\fP target dependencies. |
| See \fBAUTOGEN_TARGET_DEPENDS\fP for reference. |
| .sp |
| By default \fI\%AUTOMOC_DEPEND_FILTERS\fP is initialized from |
| \fBCMAKE_AUTOMOC_DEPEND_FILTERS\fP, which is empty by default. |
| .sp |
| From Qt 5.15.0 on this variable is ignored as moc is able to output the correct |
| dependencies. |
| .sp |
| See the \fBcmake\-qt(7)\fP manual for more information on using CMake |
| with Qt. |
| .SS Example 1 |
| .sp |
| A header file \fBmy_class.hpp\fP uses a custom macro \fBJSON_FILE_MACRO\fP which |
| is defined in an other header \fBmacros.hpp\fP\&. |
| We want the \fBmoc\fP file of \fBmy_class.hpp\fP to depend on the file name |
| argument of \fBJSON_FILE_MACRO\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| // my_class.hpp |
| class My_Class : public QObject |
| { |
| Q_OBJECT |
| JSON_FILE_MACRO ( "info.json" ) |
| \&... |
| }; |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In \fBCMakeLists.txt\fP we add a filter to |
| \fBCMAKE_AUTOMOC_DEPEND_FILTERS\fP like this: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list( APPEND CMAKE_AUTOMOC_DEPEND_FILTERS |
| "JSON_FILE_MACRO" |
| "[\en][ \et]*JSON_FILE_MACRO[ \et]*\e\e([ \et]*\e"([^\e"]+)\e"" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| We assume \fBinfo.json\fP is a plain (not \fBGENERATED\fP) file that is |
| listed in the target\(aqs source. Therefore we do not need to add it to |
| \fBAUTOGEN_TARGET_DEPENDS\fP\&. |
| .SS Example 2 |
| .sp |
| In the target \fBmy_target\fP a header file \fBcomplex_class.hpp\fP uses a |
| custom macro \fBJSON_BASED_CLASS\fP which is defined in an other header |
| \fBmacros.hpp\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| // macros.hpp |
| \&... |
| #define JSON_BASED_CLASS(name, json) \e |
| class name : public QObject \e |
| { \e |
| Q_OBJECT \e |
| Q_PLUGIN_METADATA(IID "demo" FILE json) \e |
| name() {} \e |
| }; |
| \&... |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| // complex_class.hpp |
| #pragma once |
| JSON_BASED_CLASS(Complex_Class, "meta.json") |
| // end of file |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Since \fBcomplex_class.hpp\fP doesn\(aqt contain a \fBQ_OBJECT\fP macro it would be |
| ignored by \fBAUTOMOC\fP\&. We change this by adding \fBJSON_BASED_CLASS\fP |
| to \fBCMAKE_AUTOMOC_MACRO_NAMES\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(APPEND CMAKE_AUTOMOC_MACRO_NAMES "JSON_BASED_CLASS") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| We want the \fBmoc\fP file of \fBcomplex_class.hpp\fP to depend on |
| \fBmeta.json\fP\&. So we add a filter to |
| \fBCMAKE_AUTOMOC_DEPEND_FILTERS\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(APPEND CMAKE_AUTOMOC_DEPEND_FILTERS |
| "JSON_BASED_CLASS" |
| "[\en^][ \et]*JSON_BASED_CLASS[ \et]*\e\e([^,]*,[ \et]*\e"([^\e"]+)\e"" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Additionally we assume \fBmeta.json\fP is \fBGENERATED\fP which is |
| why we have to add it to \fBAUTOGEN_TARGET_DEPENDS\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET my_target APPEND PROPERTY AUTOGEN_TARGET_DEPENDS "meta.json") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS AUTOMOC_EXECUTABLE |
| .sp |
| New in version 3.14. |
| |
| .sp |
| \fI\%AUTOMOC_EXECUTABLE\fP is file path pointing to the \fBmoc\fP |
| executable to use for \fBAUTOMOC\fP enabled files. Setting |
| this property will make CMake skip the automatic detection of the |
| \fBmoc\fP binary as well as the sanity\-tests normally run to ensure |
| that the binary is available and working as expected. |
| .sp |
| Usually this property does not need to be set. Only consider this |
| property if auto\-detection of \fBmoc\fP can not work \-\- e.g. because |
| you are building the \fBmoc\fP binary as part of your project. |
| .sp |
| See the \fBcmake\-qt(7)\fP manual for more information on using CMake |
| with Qt. |
| .SS AUTOMOC_MACRO_NAMES |
| .sp |
| New in version 3.10. |
| |
| .sp |
| A semicolon\-separated list list of macro names used by |
| \fBAUTOMOC\fP to determine if a C++ file needs to be processed by \fBmoc\fP\&. |
| .sp |
| This property is only used if the \fBAUTOMOC\fP property is \fBON\fP |
| for this target. |
| .sp |
| When running \fBAUTOMOC\fP, CMake searches for the strings listed in |
| \fI\%AUTOMOC_MACRO_NAMES\fP in C++ source and header files. |
| If any of the strings is found |
| .INDENT 0.0 |
| .IP \(bu 2 |
| as the first non space string on a new line or |
| .IP \(bu 2 |
| as the first non space string after a \fB{\fP on a new line, |
| .UNINDENT |
| .sp |
| then the file will be processed by \fBmoc\fP\&. |
| .sp |
| By default \fI\%AUTOMOC_MACRO_NAMES\fP is initialized from |
| \fBCMAKE_AUTOMOC_MACRO_NAMES\fP\&. |
| .sp |
| See the \fBcmake\-qt(7)\fP manual for more information on using CMake |
| with Qt. |
| .SS Example |
| .sp |
| In this case the \fBQ_OBJECT\fP macro is hidden inside another macro |
| called \fBCUSTOM_MACRO\fP\&. To let CMake know that source files that contain |
| \fBCUSTOM_MACRO\fP need to be \fBmoc\fP processed, we call: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET tgt APPEND PROPERTY AUTOMOC_MACRO_NAMES "CUSTOM_MACRO") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS AUTOMOC_MOC_OPTIONS |
| .sp |
| Additional options for \fBmoc\fP when using \fBAUTOMOC\fP |
| .sp |
| This property is only used if the \fBAUTOMOC\fP property is \fBON\fP |
| for this target. In this case, it holds additional command line |
| options which will be used when \fBmoc\fP is executed during the build, i.e. |
| it is equivalent to the optional \fBOPTIONS\fP argument of the |
| \fBqt4_wrap_cpp()\fP macro. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_AUTOMOC_MOC_OPTIONS\fP variable if it is set when a target |
| is created, or an empty string otherwise. |
| .sp |
| See the \fBcmake\-qt(7)\fP manual for more information on using CMake |
| with Qt. |
| .SS AUTOMOC_PATH_PREFIX |
| .sp |
| New in version 3.16. |
| |
| .sp |
| When this property is \fBON\fP, CMake will generate the \fB\-p\fP path prefix |
| option for \fBmoc\fP on \fBAUTOMOC\fP enabled Qt targets. |
| .sp |
| To generate the path prefix, CMake tests if the header compiled by \fBmoc\fP |
| is in any of the target |
| \fBinclude directories\fP\&. If so, CMake will |
| compute the relative path accordingly. If the header is not in the |
| \fBinclude directories\fP, CMake will omit |
| the \fB\-p\fP path prefix option. \fBmoc\fP usually generates a |
| relative include path in that case. |
| .sp |
| \fI\%AUTOMOC_PATH_PREFIX\fP is initialized from the variable |
| \fBCMAKE_AUTOMOC_PATH_PREFIX\fP, which is \fBOFF\fP by default. |
| .sp |
| See the \fBcmake\-qt(7)\fP manual for more information on using CMake |
| with Qt. |
| .SS Reproducible builds |
| .sp |
| For reproducible builds it is recommended to keep headers that are \fBmoc\fP |
| compiled in one of the target |
| \fBinclude directories\fP and set |
| \fI\%AUTOMOC_PATH_PREFIX\fP to \fBON\fP\&. This ensures that: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBmoc\fP output files are identical on different build setups, |
| .IP \(bu 2 |
| \fBmoc\fP output files will compile correctly when the source and/or |
| build directory is a symbolic link. |
| .UNINDENT |
| .SS AUTORCC |
| .sp |
| Should the target be processed with auto\-rcc (for Qt projects). |
| .sp |
| \fI\%AUTORCC\fP is a boolean specifying whether CMake will handle |
| the Qt \fBrcc\fP code generator automatically, i.e. without having to use |
| commands like \fBQT4_ADD_RESOURCES()\fP, \fBQT5_ADD_RESOURCES()\fP, |
| etc. Currently, Qt versions 4 to 6 are supported. |
| .sp |
| When this property is \fBON\fP, CMake will handle \fB\&.qrc\fP files added |
| as target sources at build time and invoke \fBrcc\fP accordingly. |
| This property is initialized by the value of the \fBCMAKE_AUTORCC\fP |
| variable if it is set when a target is created. |
| .sp |
| By default \fI\%AUTORCC\fP is processed by a |
| \fBcustom command\fP\&. |
| If the \fB\&.qrc\fP file is \fBGENERATED\fP, a |
| \fBcustom target\fP is used instead. |
| .sp |
| When there are multiple \fB\&.qrc\fP files with the same name, CMake will |
| generate unspecified unique output file names for \fBrcc\fP\&. Therefore, if |
| \fBQ_INIT_RESOURCE()\fP or \fBQ_CLEANUP_RESOURCE()\fP need to be used, the |
| \fB\&.qrc\fP file name must be unique. |
| .SS Modifiers |
| .sp |
| \fBAUTORCC_EXECUTABLE\fP: |
| The \fBrcc\fP executable will be detected automatically, but can be forced to |
| a certain binary by setting this target property. |
| .sp |
| \fBAUTORCC_OPTIONS\fP: |
| Additional command line options for \fBrcc\fP can be set via this target |
| property. The corresponding \fBAUTORCC_OPTIONS\fP source file property |
| can be used to specify options to be applied only to a specific \fB\&.qrc\fP file. |
| .sp |
| \fBSKIP_AUTORCC\fP: |
| \fB\&.qrc\fP files can be excluded from \fI\%AUTORCC\fP processing by |
| setting this source file property. |
| .sp |
| \fBSKIP_AUTOGEN\fP: |
| Source files can be excluded from \fBAUTOMOC\fP, |
| \fBAUTOUIC\fP and \fI\%AUTORCC\fP processing by |
| setting this source file property. |
| .sp |
| \fBAUTOGEN_SOURCE_GROUP\fP: |
| This global property can be used to group files generated by |
| \fBAUTOMOC\fP or \fI\%AUTORCC\fP together in an IDE, e.g. in MSVS. |
| .sp |
| \fBAUTOGEN_TARGETS_FOLDER\fP: |
| This global property can be used to group \fBAUTOMOC\fP, |
| \fBAUTOUIC\fP and \fI\%AUTORCC\fP targets together in an IDE, |
| e.g. in MSVS. |
| .sp |
| \fBCMAKE_GLOBAL_AUTORCC_TARGET\fP: |
| A global \fBautorcc\fP target that depends on all \fI\%AUTORCC\fP targets |
| in the project will be generated when this variable is \fBON\fP\&. |
| .sp |
| See the \fBcmake\-qt(7)\fP manual for more information on using CMake |
| with Qt. |
| .SS AUTORCC_EXECUTABLE |
| .sp |
| New in version 3.14. |
| |
| .sp |
| \fI\%AUTORCC_EXECUTABLE\fP is file path pointing to the \fBrcc\fP |
| executable to use for \fBAUTORCC\fP enabled files. Setting |
| this property will make CMake skip the automatic detection of the |
| \fBrcc\fP binary as well as the sanity\-tests normally run to ensure |
| that the binary is available and working as expected. |
| .sp |
| Usually this property does not need to be set. Only consider this |
| property if auto\-detection of \fBrcc\fP can not work \-\- e.g. because |
| you are building the \fBrcc\fP binary as part of your project. |
| .sp |
| See the \fBcmake\-qt(7)\fP manual for more information on using CMake |
| with Qt. |
| .SS AUTORCC_OPTIONS |
| .sp |
| Additional options for \fBrcc\fP when using \fBAUTORCC\fP |
| .sp |
| This property holds additional command line options which will be used |
| when \fBrcc\fP is executed during the build via \fBAUTORCC\fP, |
| i.e. it is equivalent to the optional \fBOPTIONS\fP argument of the |
| \fBqt4_add_resources()\fP macro. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_AUTORCC_OPTIONS\fP variable if it is set when a target is |
| created, or an empty string otherwise. |
| .sp |
| The options set on the target may be overridden by \fBAUTORCC_OPTIONS\fP |
| set on the \fB\&.qrc\fP source file. |
| .sp |
| See the \fBcmake\-qt(7)\fP manual for more information on using CMake |
| with Qt. |
| .SS EXAMPLE |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # ... |
| set_property(TARGET tgt PROPERTY AUTORCC_OPTIONS "\-\-compress;9") |
| # ... |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS AUTOUIC |
| .sp |
| Should the target be processed with auto\-uic (for Qt projects). |
| .sp |
| \fI\%AUTOUIC\fP is a boolean specifying whether CMake will handle |
| the Qt \fBuic\fP code generator automatically, i.e. without having to use |
| commands like \fBQT4_WRAP_UI()\fP, \fBQT5_WRAP_UI()\fP, etc. |
| Currently, Qt versions 4 to 6 are supported. |
| .sp |
| This property is initialized by the value of the \fBCMAKE_AUTOUIC\fP |
| variable if it is set when a target is created. |
| .sp |
| When this property is \fBON\fP, CMake will scan the header and source files at |
| build time and invoke \fBuic\fP accordingly. |
| .SS Header and source file processing |
| .sp |
| At build time, CMake scans each header and source file from the |
| target\(aqs sources for include statements of the form |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #include "ui_<ui_base>.h" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Once such an include statement is found in a file, CMake searches for the |
| \fBuic\fP input file \fB<ui_base>.ui\fP |
| .INDENT 0.0 |
| .IP \(bu 2 |
| in the vicinity of the file and |
| .IP \(bu 2 |
| in the \fBAUTOUIC_SEARCH_PATHS\fP of the target. |
| .UNINDENT |
| .sp |
| If the \fB<ui_base>.ui\fP file was found, \fBuic\fP is called on it to generate |
| \fBui_<ui_base>.h\fP in the directory |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fB<AUTOGEN_BUILD_DIR>/include\fP for single configuration generators or in |
| .IP \(bu 2 |
| \fB<AUTOGEN_BUILD_DIR>/include_<CONFIG>\fP for |
| \fBmulti configuration\fP generators. |
| .UNINDENT |
| .sp |
| Where \fB<AUTOGEN_BUILD_DIR>\fP is the value of the target property |
| \fBAUTOGEN_BUILD_DIR\fP\&. |
| .sp |
| The include directory is automatically added to the target\(aqs |
| \fBINCLUDE_DIRECTORIES\fP\&. |
| .SS Modifiers |
| .sp |
| \fBAUTOUIC_EXECUTABLE\fP: |
| The \fBuic\fP executable will be detected automatically, but can be forced to |
| a certain binary using this target property. |
| .sp |
| \fBAUTOUIC_OPTIONS\fP: |
| Additional command line options for \fBuic\fP can be set via this target |
| property. The corresponding \fBAUTOUIC_OPTIONS\fP source file property |
| can be used to specify options to be applied only to a specific |
| \fB<base_name>.ui\fP file. |
| .sp |
| \fBSKIP_AUTOUIC\fP: |
| Source files can be excluded from \fI\%AUTOUIC\fP processing by setting |
| this source file property. |
| .sp |
| \fBSKIP_AUTOGEN\fP: |
| Source files can be excluded from \fBAUTOMOC\fP, |
| \fI\%AUTOUIC\fP and \fBAUTORCC\fP processing by |
| setting this source file property. |
| .sp |
| \fBAUTOGEN_TARGETS_FOLDER\fP: |
| This global property can be used to group \fBAUTOMOC\fP, |
| \fI\%AUTOUIC\fP and \fBAUTORCC\fP targets together in an IDE, |
| e.g. in MSVS. |
| .sp |
| \fBCMAKE_GLOBAL_AUTOGEN_TARGET\fP: |
| A global \fBautogen\fP target, that depends on all \fBAUTOMOC\fP or |
| \fI\%AUTOUIC\fP generated \fB<ORIGIN>_autogen\fP targets in the project, |
| will be generated when this variable is \fBON\fP\&. |
| .sp |
| \fBAUTOGEN_PARALLEL\fP: |
| This target property controls the number of \fBmoc\fP or \fBuic\fP processes to |
| start in parallel during builds. |
| .sp |
| See the \fBcmake\-qt(7)\fP manual for more information on using CMake |
| with Qt. |
| .SS AUTOUIC_EXECUTABLE |
| .sp |
| New in version 3.14. |
| |
| .sp |
| \fI\%AUTOUIC_EXECUTABLE\fP is file path pointing to the \fBuic\fP |
| executable to use for \fBAUTOUIC\fP enabled files. Setting |
| this property will make CMake skip the automatic detection of the |
| \fBuic\fP binary as well as the sanity\-tests normally run to ensure |
| that the binary is available and working as expected. |
| .sp |
| Usually this property does not need to be set. Only consider this |
| property if auto\-detection of \fBuic\fP can not work \-\- e.g. because |
| you are building the \fBuic\fP binary as part of your project. |
| .sp |
| See the \fBcmake\-qt(7)\fP manual for more information on using CMake |
| with Qt. |
| .SS AUTOUIC_OPTIONS |
| .sp |
| Additional options for \fBuic\fP when using \fBAUTOUIC\fP |
| .sp |
| This property holds additional command line options which will be used when |
| \fBuic\fP is executed during the build via \fBAUTOUIC\fP, i.e. it is |
| equivalent to the optional \fBOPTIONS\fP argument of the |
| \fBqt4_wrap_ui()\fP macro. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_AUTOUIC_OPTIONS\fP variable if it is set when a target is |
| created, or an empty string otherwise. |
| .sp |
| The options set on the target may be overridden by \fBAUTOUIC_OPTIONS\fP |
| set on the \fB\&.ui\fP source file. |
| .sp |
| This property may use "generator expressions" with the syntax \fB$<...>\fP\&. |
| See the \fBcmake\-generator\-expressions(7)\fP manual for available |
| expressions. |
| .sp |
| See the \fBcmake\-qt(7)\fP manual for more information on using CMake |
| with Qt. |
| .SS EXAMPLE |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # ... |
| set_property(TARGET tgt PROPERTY AUTOUIC_OPTIONS "\-\-no\-protection") |
| # ... |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS AUTOUIC_SEARCH_PATHS |
| .sp |
| New in version 3.9. |
| |
| .sp |
| Search path list used by \fBAUTOUIC\fP to find included |
| \fB\&.ui\fP files. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_AUTOUIC_SEARCH_PATHS\fP variable if it is set |
| when a target is created. Otherwise it is empty. |
| .sp |
| See the \fBcmake\-qt(7)\fP manual for more information on using CMake |
| with Qt. |
| .SS BINARY_DIR |
| .sp |
| New in version 3.4. |
| |
| .sp |
| This read\-only property reports the value of the |
| \fBCMAKE_CURRENT_BINARY_DIR\fP variable in the directory in which |
| the target was defined. |
| .SS BUILD_RPATH |
| .sp |
| New in version 3.8. |
| |
| .sp |
| A semicolon\-separated list specifying runtime path (\fBRPATH\fP) |
| entries to add to binaries linked in the build tree (for platforms that |
| support it). The entries will \fInot\fP be used for binaries in the install |
| tree. See also the \fBINSTALL_RPATH\fP target property. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_BUILD_RPATH\fP if it is set when a target is created. |
| .sp |
| This property supports |
| \fBgenerator expressions\fP\&. |
| .SS BUILD_RPATH_USE_ORIGIN |
| .sp |
| New in version 3.14. |
| |
| .sp |
| Whether to use relative paths for the build \fBRPATH\fP\&. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_BUILD_RPATH_USE_ORIGIN\fP\&. |
| .sp |
| On platforms that support runtime paths (\fBRPATH\fP) with the |
| \fB$ORIGIN\fP token, setting this property to \fBTRUE\fP enables relative |
| paths in the build \fBRPATH\fP for executables and shared libraries that |
| point to shared libraries in the same build tree. |
| .sp |
| Normally the build \fBRPATH\fP of a binary contains absolute paths |
| to the directory of each shared library it links to. The \fBRPATH\fP |
| entries for directories contained within the build tree can be made |
| relative to enable relocatable builds and to help achieve reproducible |
| builds by omitting the build directory from the build environment. |
| .sp |
| This property has no effect on platforms that do not support the |
| \fB$ORIGIN\fP token in \fBRPATH\fP, or when the \fBCMAKE_SKIP_RPATH\fP |
| variable is set. The runtime path set through the |
| \fBBUILD_RPATH\fP target property is also unaffected by this |
| property. |
| .SS BUILD_WITH_INSTALL_NAME_DIR |
| .sp |
| New in version 3.9. |
| |
| .sp |
| \fBBUILD_WITH_INSTALL_NAME_DIR\fP is a boolean specifying whether the macOS |
| \fBinstall_name\fP of a target in the build tree uses the directory given by |
| \fBINSTALL_NAME_DIR\fP\&. This setting only applies to targets on macOS. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_BUILD_WITH_INSTALL_NAME_DIR\fP if it is set when a target is |
| created. |
| .sp |
| If this property is not set and policy \fBCMP0068\fP is not \fBNEW\fP, the |
| value of \fBBUILD_WITH_INSTALL_RPATH\fP is used in its place. |
| .SS BUILD_WITH_INSTALL_RPATH |
| .sp |
| \fBBUILD_WITH_INSTALL_RPATH\fP is a boolean specifying whether to link the target |
| in the build tree with the \fBINSTALL_RPATH\fP\&. This takes precedence |
| over \fBSKIP_BUILD_RPATH\fP and avoids the need for relinking before |
| installation. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_BUILD_WITH_INSTALL_RPATH\fP variable if it is set when a target |
| is created. |
| .sp |
| If policy \fBCMP0068\fP is not \fBNEW\fP, this property also controls use of |
| \fBINSTALL_NAME_DIR\fP in the build tree on macOS. Either way, the |
| \fBBUILD_WITH_INSTALL_NAME_DIR\fP target property takes precedence. |
| .SS BUNDLE |
| .sp |
| This target is a \fBCFBundle\fP on the macOS. |
| .sp |
| If a module library target has this property set to true it will be |
| built as a \fBCFBundle\fP when built on the mac. It will have the directory |
| structure required for a \fBCFBundle\fP and will be suitable to be used for |
| creating Browser Plugins or other application resources. |
| .SS BUNDLE_EXTENSION |
| .sp |
| The file extension used to name a \fBBUNDLE\fP, a \fBFRAMEWORK\fP, |
| or a \fBMACOSX_BUNDLE\fP target on the macOS and iOS. |
| .sp |
| The default value is \fBbundle\fP, \fBframework\fP, or \fBapp\fP for the respective |
| target types. |
| .SS C_EXTENSIONS |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Boolean specifying whether compiler specific extensions are requested. |
| .sp |
| This property specifies whether compiler specific extensions should be |
| used. For some compilers, this results in adding a flag such |
| as \fB\-std=gnu11\fP instead of \fB\-std=c11\fP to the compile line. This |
| property is \fBON\fP by default. The basic C standard level is |
| controlled by the \fBC_STANDARD\fP target property. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_C_EXTENSIONS\fP variable if set when a target is created and |
| otherwise by the value of |
| \fBCMAKE_C_EXTENSIONS_DEFAULT\fP (see |
| \fBCMP0128\fP). |
| .SS C_STANDARD |
| .sp |
| New in version 3.1. |
| |
| .sp |
| The C standard whose features are requested to build this target. |
| .sp |
| This property specifies the C standard whose features are requested |
| to build this target. For some compilers, this results in adding a |
| flag such as \fB\-std=gnu11\fP to the compile line. For compilers that |
| have no notion of a C standard level, such as Microsoft Visual C++ before |
| VS 16.7, this property has no effect. |
| .sp |
| Supported values are: |
| .INDENT 0.0 |
| .TP |
| .B \fB90\fP |
| C89/C90 |
| .TP |
| .B \fB99\fP |
| C99 |
| .TP |
| .B \fB11\fP |
| C11 |
| .TP |
| .B \fB17\fP |
| New in version 3.21. |
| |
| .sp |
| C17 |
| .TP |
| .B \fB23\fP |
| New in version 3.21. |
| |
| .sp |
| C23 |
| .UNINDENT |
| .sp |
| If the value requested does not result in a compile flag being added for |
| the compiler in use, a previous standard flag will be added instead. This |
| means that using: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET tgt PROPERTY C_STANDARD 11) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| with a compiler which does not support \fB\-std=gnu11\fP or an equivalent |
| flag will not result in an error or warning, but will instead add the |
| \fB\-std=gnu99\fP or \fB\-std=gnu90\fP flag if supported. This "decay" behavior may |
| be controlled with the \fBC_STANDARD_REQUIRED\fP target property. |
| Additionally, the \fBC_EXTENSIONS\fP target property may be used to |
| control whether compiler\-specific extensions are enabled on a per\-target basis. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_C_STANDARD\fP variable if it is set when a target |
| is created. |
| .SS C_STANDARD_REQUIRED |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Boolean describing whether the value of \fBC_STANDARD\fP is a requirement. |
| .sp |
| If this property is set to \fBON\fP, then the value of the |
| \fBC_STANDARD\fP target property is treated as a requirement. If this |
| property is \fBOFF\fP or unset, the \fBC_STANDARD\fP target property is |
| treated as optional and may "decay" to a previous standard if the requested is |
| not available. For compilers that have no notion of a C standard level, such |
| as Microsoft Visual C++ before VS 16.7, this property has no effect. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_C_STANDARD_REQUIRED\fP variable if it is set when a |
| target is created. |
| .SS COMMON_LANGUAGE_RUNTIME |
| .sp |
| New in version 3.12. |
| |
| .sp |
| By setting this target property, the target is configured to build with |
| \fBC++/CLI\fP support. |
| .sp |
| The Visual Studio generator defines the \fBclr\fP parameter depending on |
| the value of \fBCOMMON_LANGUAGE_RUNTIME\fP: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| property not set: native C++ (i.e. default) |
| .IP \(bu 2 |
| property set but empty: mixed unmanaged/managed C++ |
| .IP \(bu 2 |
| property set to any non empty value: managed C++ |
| .UNINDENT |
| .sp |
| Supported values: \fB""\fP, \fB"pure"\fP, \fB"safe"\fP |
| .sp |
| This property is only evaluated Visual Studio Generators for |
| VS 2010 and above. |
| .sp |
| To be able to build managed C++ targets with VS 2017 and above the component |
| \fBC++/CLI support\fP must be installed, which may not be done by default. |
| .sp |
| See also \fBIMPORTED_COMMON_LANGUAGE_RUNTIME\fP |
| .SS COMPATIBLE_INTERFACE_BOOL |
| .sp |
| Properties which must be compatible with their link interface |
| .sp |
| The \fBCOMPATIBLE_INTERFACE_BOOL\fP property may contain a list of |
| properties for this target which must be consistent when evaluated as a |
| boolean with the \fBINTERFACE\fP variant of the property in all linked |
| dependees. For example, if a property \fBFOO\fP appears in the list, then |
| for each dependee, the \fBINTERFACE_FOO\fP property content in all of its |
| dependencies must be consistent with each other, and with the \fBFOO\fP |
| property in the depender. |
| .sp |
| Consistency in this sense has the meaning that if the property is set, |
| then it must have the same boolean value as all others, and if the |
| property is not set, then it is ignored. |
| .sp |
| Note that for each dependee, the set of properties specified in this |
| property must not intersect with the set specified in any of the other |
| Compatible Interface Properties\&. |
| .SS COMPATIBLE_INTERFACE_NUMBER_MAX |
| .sp |
| Properties whose maximum value from the link interface will be used. |
| .sp |
| The \fBCOMPATIBLE_INTERFACE_NUMBER_MAX\fP property may contain a list of |
| properties for this target whose maximum value may be read at generate |
| time when evaluated in the \fBINTERFACE\fP variant of the property in all |
| linked dependees. For example, if a property \fBFOO\fP appears in the list, |
| then for each dependee, the \fBINTERFACE_FOO\fP property content in all of |
| its dependencies will be compared with each other and with the \fBFOO\fP |
| property in the depender. When reading the \fBFOO\fP property at generate |
| time, the maximum value will be returned. If the property is not set, |
| then it is ignored. |
| .sp |
| Note that for each dependee, the set of properties specified in this |
| property must not intersect with the set specified in any of the other |
| Compatible Interface Properties\&. |
| .SS COMPATIBLE_INTERFACE_NUMBER_MIN |
| .sp |
| Properties whose maximum value from the link interface will be used. |
| .sp |
| The \fBCOMPATIBLE_INTERFACE_NUMBER_MIN\fP property may contain a list of |
| properties for this target whose minimum value may be read at generate |
| time when evaluated in the \fBINTERFACE\fP variant of the property of all |
| linked dependees. For example, if a |
| property \fBFOO\fP appears in the list, then for each dependee, the |
| \fBINTERFACE_FOO\fP property content in all of its dependencies will be |
| compared with each other and with the \fBFOO\fP property in the depender. |
| When reading the \fBFOO\fP property at generate time, the minimum value |
| will be returned. If the property is not set, then it is ignored. |
| .sp |
| Note that for each dependee, the set of properties specified in this |
| property must not intersect with the set specified in any of the other |
| Compatible Interface Properties\&. |
| .SS COMPATIBLE_INTERFACE_STRING |
| .sp |
| Properties which must be string\-compatible with their link interface |
| .sp |
| The \fBCOMPATIBLE_INTERFACE_STRING\fP property may contain a list of |
| properties for this target which must be the same when evaluated as a |
| string in the \fBINTERFACE\fP variant of the property all linked dependees. |
| For example, if a property \fBFOO\fP appears in the list, then for each |
| dependee, the \fBINTERFACE_FOO\fP property content in all of its |
| dependencies must be equal with each other, and with the \fBFOO\fP property |
| in the depender. If the property is not set, then it is ignored. |
| .sp |
| Note that for each dependee, the set of properties specified in this |
| property must not intersect with the set specified in any of the other |
| Compatible Interface Properties\&. |
| .SS COMPILE_DEFINITIONS |
| .sp |
| Preprocessor definitions for compiling a target\(aqs sources. |
| .sp |
| The \fBCOMPILE_DEFINITIONS\fP property may be set to a semicolon\-separated |
| list of preprocessor definitions using the syntax \fBVAR\fP or \fBVAR=value\fP\&. |
| Function\-style definitions are not supported. CMake will |
| automatically escape the value correctly for the native build system |
| (note that CMake language syntax may require escapes to specify some |
| values). |
| .sp |
| CMake will automatically drop some definitions that are not supported |
| by the native build tool. |
| .sp |
| Disclaimer: Most native build tools have poor support for escaping |
| certain values. CMake has work\-arounds for many cases but some values |
| may just not be possible to pass correctly. If a value does not seem |
| to be escaped correctly, do not attempt to work\-around the problem by |
| adding escape sequences to the value. Your work\-around may break in a |
| future version of CMake that has improved escape support. Instead |
| consider defining the macro in a (configured) header file. Then |
| report the limitation. Known limitations include: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # \- broken almost everywhere |
| ; \- broken in VS IDE 7.0 and Borland Makefiles |
| , \- broken in VS IDE |
| % \- broken in some cases in NMake |
| & | \- broken in some cases on MinGW |
| ^ < > \e" \- broken in most Make tools on Windows |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| CMake does not reject these values outright because they do work in |
| some cases. Use with caution. |
| .sp |
| Contents of \fBCOMPILE_DEFINITIONS\fP may use "generator expressions" with the |
| syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP manual |
| for available expressions. See the \fBcmake\-buildsystem(7)\fP manual |
| for more on defining buildsystem properties. |
| .sp |
| The corresponding \fBCOMPILE_DEFINITIONS_<CONFIG>\fP property may |
| be set to specify per\-configuration definitions. Generator expressions |
| should be preferred instead of setting the alternative property. |
| .SS COMPILE_FEATURES |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Compiler features enabled for this target. |
| .sp |
| The list of features in this property are a subset of the features listed |
| in the \fBCMAKE_C_COMPILE_FEATURES\fP, \fBCMAKE_CUDA_COMPILE_FEATURES\fP, and |
| \fBCMAKE_CXX_COMPILE_FEATURES\fP variables. |
| .sp |
| Contents of \fBCOMPILE_FEATURES\fP may use "generator expressions" with the |
| syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP manual for |
| available expressions. See the \fBcmake\-compile\-features(7)\fP manual |
| for information on compile features and a list of supported compilers. |
| .SS COMPILE_FLAGS |
| .sp |
| Additional flags to use when compiling this target\(aqs sources. |
| .sp |
| The \fBCOMPILE_FLAGS\fP property sets additional compiler flags used to |
| build sources within the target. Use \fBCOMPILE_DEFINITIONS\fP |
| to pass additional preprocessor definitions. |
| .sp |
| This property is deprecated. Use the \fBCOMPILE_OPTIONS\fP |
| property or the \fBtarget_compile_options()\fP command instead. |
| .SS COMPILE_OPTIONS |
| .sp |
| List of options to pass to the compiler. |
| .sp |
| This property holds a semicolon\-separated list |
| of options specified so far for its target. Use the |
| \fBtarget_compile_options()\fP command to append more options. |
| The options will be added after after flags in the |
| \fBCMAKE_<LANG>_FLAGS\fP and \fBCMAKE_<LANG>_FLAGS_<CONFIG>\fP |
| variables, but before those propagated from dependencies by the |
| \fBINTERFACE_COMPILE_OPTIONS\fP property. |
| .sp |
| This property is initialized by the \fBCOMPILE_OPTIONS\fP directory |
| property when a target is created, and is used by the generators to set |
| the options for the compiler. |
| .sp |
| Contents of \fBCOMPILE_OPTIONS\fP may use "generator expressions" with the |
| syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP manual |
| for available expressions. See the \fBcmake\-buildsystem(7)\fP manual |
| for more on defining buildsystem properties. |
| .SS Option De\-duplication |
| .sp |
| The final set of options used for a target is constructed by |
| accumulating options from the current target and the usage requirements of |
| its dependencies. The set of options is de\-duplicated to avoid repetition. |
| .sp |
| New in version 3.12: While beneficial for individual options, the de\-duplication step can break |
| up option groups. For example, \fB\-option A \-option B\fP becomes |
| \fB\-option A B\fP\&. One may specify a group of options using shell\-like |
| quoting along with a \fBSHELL:\fP prefix. The \fBSHELL:\fP prefix is dropped, |
| and the rest of the option string is parsed using the |
| \fBseparate_arguments()\fP \fBUNIX_COMMAND\fP mode. For example, |
| \fB"SHELL:\-option A" "SHELL:\-option B"\fP becomes \fB\-option A \-option B\fP\&. |
| |
| .SS COMPILE_PDB_NAME |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Output name for the MS debug symbol \fB\&.pdb\fP file generated by the |
| compiler while building source files. |
| .sp |
| This property specifies the base name for the debug symbols file. |
| If not set, the default is unspecified. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The compiler\-generated program database files are specified by the |
| \fB/Fd\fP compiler flag and are not the same as linker\-generated |
| program database files specified by the \fB/pdb\fP linker flag. |
| Use the \fBPDB_NAME\fP property to specify the latter. |
| .UNINDENT |
| .UNINDENT |
| .SS COMPILE_PDB_NAME_<CONFIG> |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Per\-configuration output name for the MS debug symbol \fB\&.pdb\fP file |
| generated by the compiler while building source files. |
| .sp |
| This is the configuration\-specific version of \fBCOMPILE_PDB_NAME\fP\&. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The compiler\-generated program database files are specified by the |
| \fB/Fd\fP compiler flag and are not the same as linker\-generated |
| program database files specified by the \fB/pdb\fP linker flag. |
| Use the \fBPDB_NAME_<CONFIG>\fP property to specify the latter. |
| .UNINDENT |
| .UNINDENT |
| .SS COMPILE_PDB_OUTPUT_DIRECTORY |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Output directory for the MS debug symbol \fB\&.pdb\fP file |
| generated by the compiler while building source files. |
| .sp |
| This property specifies the directory into which the MS debug symbols |
| will be placed by the compiler. This property is initialized by the |
| value of the \fBCMAKE_COMPILE_PDB_OUTPUT_DIRECTORY\fP variable |
| if it is set when a target is created. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The compiler\-generated program database files are specified by the |
| \fB/Fd\fP compiler flag and are not the same as linker\-generated |
| program database files specified by the \fB/pdb\fP linker flag. |
| Use the \fBPDB_OUTPUT_DIRECTORY\fP property to specify the latter. |
| .UNINDENT |
| .UNINDENT |
| .SS COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Per\-configuration output directory for the MS debug symbol \fB\&.pdb\fP file |
| generated by the compiler while building source files. |
| .sp |
| This is a per\-configuration version of |
| \fBCOMPILE_PDB_OUTPUT_DIRECTORY\fP, |
| but multi\-configuration generators (Visual Studio, Xcode) do NOT append a |
| per\-configuration subdirectory to the specified directory. This |
| property is initialized by the value of the |
| \fBCMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>\fP variable |
| if it is set when a target is created. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The compiler\-generated program database files are specified by the |
| \fB/Fd\fP compiler flag and are not the same as linker\-generated |
| program database files specified by the \fB/pdb\fP linker flag. |
| Use the \fBPDB_OUTPUT_DIRECTORY_<CONFIG>\fP property to specify the latter. |
| .UNINDENT |
| .UNINDENT |
| .SS <CONFIG>_OUTPUT_NAME |
| .sp |
| Old per\-configuration target file base name. |
| Use \fBOUTPUT_NAME_<CONFIG>\fP instead. |
| .sp |
| This is a configuration\-specific version of the \fBOUTPUT_NAME\fP |
| target property. |
| .SS <CONFIG>_POSTFIX |
| .sp |
| Postfix to append to the target file name for configuration <CONFIG>. |
| .sp |
| When building with configuration <CONFIG> the value of this property |
| is appended to the target file name built on disk. For non\-executable |
| targets, this property is initialized by the value of the variable |
| CMAKE_<CONFIG>_POSTFIX if it is set when a target is created. This |
| property is ignored on the Mac for Frameworks and App Bundles. |
| .sp |
| For macOS see also the \fBFRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>\fP |
| target property. |
| .SS CROSSCOMPILING_EMULATOR |
| .sp |
| New in version 3.3. |
| |
| .sp |
| Use the given emulator to run executables created when crosscompiling. |
| This command will be added as a prefix to \fBadd_test()\fP, |
| \fBadd_custom_command()\fP, and \fBadd_custom_target()\fP commands |
| for built target system executables. |
| .sp |
| New in version 3.15: If this property contains a semicolon\-separated list, then the first value is the command and remaining values are its |
| arguments. |
| |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_CROSSCOMPILING_EMULATOR\fP variable if it is set when a target |
| is created. |
| .SS CUDA_ARCHITECTURES |
| .sp |
| New in version 3.18. |
| |
| .sp |
| List of architectures to generate device code for. |
| .sp |
| An architecture can be suffixed by either \fB\-real\fP or \fB\-virtual\fP to specify |
| the kind of architecture to generate code for. |
| If no suffix is given then code is generated for both real and virtual |
| architectures. |
| .sp |
| A non\-empty false value (e.g. \fBOFF\fP) disables adding architectures. |
| This is intended to support packagers and rare cases where full control |
| over the passed flags is required. |
| .sp |
| This property is initialized by the value of the \fBCMAKE_CUDA_ARCHITECTURES\fP |
| variable if it is set when a target is created. |
| .sp |
| The \fBCUDA_ARCHITECTURES\fP target property must be set to a non\-empty value on targets |
| that compile CUDA sources, or it is an error. See policy \fBCMP0104\fP\&. |
| .sp |
| The \fBCUDA_ARCHITECTURES\fP may be set to one of the following special values: |
| .INDENT 0.0 |
| .TP |
| .B \fBall\fP |
| New in version 3.23. |
| |
| .sp |
| Compile for all supported major and minor real architectures, |
| and the highest major virtual architecture. |
| .TP |
| .B \fBall\-major\fP |
| New in version 3.23. |
| |
| .sp |
| Compile for all supported major real architectures, and the highest |
| major virtual architecture. |
| .UNINDENT |
| .SS Examples |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_target_properties(tgt PROPERTIES CUDA_ARCHITECTURES "35;50;72") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Generates code for real and virtual architectures \fB30\fP, \fB50\fP and \fB72\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 70\-real 72\-virtual) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Generates code for real architecture \fB70\fP and virtual architecture \fB72\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES OFF) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| CMake will not pass any architecture flags to the compiler. |
| .SS CUDA_EXTENSIONS |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Boolean specifying whether compiler specific extensions are requested. |
| .sp |
| This property specifies whether compiler specific extensions should be |
| used. For some compilers, this results in adding a flag such |
| as \fB\-std=gnu++11\fP instead of \fB\-std=c++11\fP to the compile line. This |
| property is \fBON\fP by default. The basic CUDA/C++ standard level is |
| controlled by the \fBCUDA_STANDARD\fP target property. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_CUDA_EXTENSIONS\fP variable if set when a target is created |
| and otherwise by the value of |
| \fBCMAKE_CUDA_EXTENSIONS_DEFAULT\fP |
| (see \fBCMP0128\fP). |
| .SS CUDA_PTX_COMPILATION |
| .sp |
| New in version 3.9. |
| |
| .sp |
| Compile CUDA sources to \fB\&.ptx\fP files instead of \fB\&.obj\fP files |
| within Object Libraries\&. |
| .sp |
| For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(myptx OBJECT a.cu b.cu) |
| set_property(TARGET myptx PROPERTY CUDA_PTX_COMPILATION ON) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS CUDA_RESOLVE_DEVICE_SYMBOLS |
| .sp |
| New in version 3.9. |
| |
| .sp |
| CUDA only: Enables device linking for the specific library target where |
| required. |
| .sp |
| If set, this will tell the required compilers to enable device linking |
| on the library target. Device linking is an additional link step |
| required by some CUDA compilers when \fBCUDA_SEPARABLE_COMPILATION\fP is |
| enabled. Normally device linking is deferred until a shared library or |
| executable is generated, allowing for multiple static libraries to resolve |
| device symbols at the same time when they are used by a shared library or |
| executable. |
| .sp |
| By default static library targets have this property is disabled, |
| while shared, module, and executable targets have this property enabled. |
| .sp |
| Note that device linking is not supported for Object Libraries\&. |
| .sp |
| For instance: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET mystaticlib PROPERTY CUDA_RESOLVE_DEVICE_SYMBOLS ON) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS CUDA_RUNTIME_LIBRARY |
| .sp |
| New in version 3.17. |
| |
| .sp |
| Select the CUDA runtime library for use by compilers targeting the CUDA language. |
| .sp |
| The allowed case insensitive values are: |
| .INDENT 0.0 |
| .TP |
| .B \fBNone\fP |
| Link with \fB\-cudart=none\fP or equivalent flag(s) to use no CUDA |
| runtime library. |
| .TP |
| .B \fBShared\fP |
| Link with \fB\-cudart=shared\fP or equivalent flag(s) to use a |
| dynamically\-linked CUDA runtime library. |
| .TP |
| .B \fBStatic\fP |
| Link with \fB\-cudart=static\fP or equivalent flag(s) to use a |
| statically\-linked CUDA runtime library. |
| .UNINDENT |
| .sp |
| Contents of \fBCUDA_RUNTIME_LIBRARY\fP may use |
| \fBgenerator expressions\fP\&. |
| .sp |
| If that property is not set then CMake uses an appropriate default |
| value based on the compiler to select the CUDA runtime library. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This property has effect only when the \fBCUDA\fP language is enabled. To |
| control the CUDA runtime linking when only using the CUDA SDK with the |
| \fBC\fP or \fBC++\fP language we recommend using the \fBFindCUDAToolkit\fP |
| module. |
| .UNINDENT |
| .UNINDENT |
| .SS CUDA_SEPARABLE_COMPILATION |
| .sp |
| New in version 3.8. |
| |
| .sp |
| CUDA only: Enables separate compilation of device code |
| .sp |
| If set this will enable separable compilation for all CUDA files for |
| the given target. |
| .sp |
| For instance: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET myexe PROPERTY CUDA_SEPARABLE_COMPILATION ON) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_CUDA_SEPARABLE_COMPILATION\fP variable if it is set when a |
| target is created. |
| .SS CUDA_STANDARD |
| .sp |
| New in version 3.8. |
| |
| .sp |
| The CUDA/C++ standard whose features are requested to build this target. |
| .sp |
| This property specifies the CUDA/C++ standard whose features are requested |
| to build this target. For some compilers, this results in adding a |
| flag such as \fB\-std=gnu++11\fP to the compile line. |
| .sp |
| Supported values are: |
| .INDENT 0.0 |
| .TP |
| .B \fB98\fP |
| CUDA C++98. Note that this maps to the same as \fB03\fP internally. |
| .TP |
| .B \fB03\fP |
| CUDA C++03 |
| .TP |
| .B \fB11\fP |
| CUDA C++11 |
| .TP |
| .B \fB14\fP |
| CUDA C++14. While CMake 3.8 and later \fIrecognize\fP \fB14\fP as a valid value, |
| CMake 3.9 was the first version to include support for any compiler. |
| .TP |
| .B \fB17\fP |
| CUDA C++17. While CMake 3.8 and later \fIrecognize\fP \fB17\fP as a valid value, |
| CMake 3.18 was the first version to include support for any compiler. |
| .TP |
| .B \fB20\fP |
| New in version 3.12. |
| |
| .sp |
| CUDA C++20. While CMake 3.12 and later \fIrecognize\fP \fB20\fP as a valid value, |
| CMake 3.18 was the first version to include support for any compiler. |
| .TP |
| .B \fB23\fP |
| New in version 3.20. |
| |
| .sp |
| CUDA C++23 |
| .UNINDENT |
| .sp |
| If the value requested does not result in a compile flag being added for |
| the compiler in use, a previous standard flag will be added instead. This |
| means that using: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET tgt PROPERTY CUDA_STANDARD 11) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| with a compiler which does not support \fB\-std=gnu++11\fP or an equivalent |
| flag will not result in an error or warning, but will instead add the |
| \fB\-std=gnu++03\fP flag if supported. This "decay" behavior may be controlled |
| with the \fBCUDA_STANDARD_REQUIRED\fP target property. |
| Additionally, the \fBCUDA_EXTENSIONS\fP target property may be used to |
| control whether compiler\-specific extensions are enabled on a per\-target basis. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_CUDA_STANDARD\fP variable if it is set when a target |
| is created. |
| .SS CUDA_STANDARD_REQUIRED |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Boolean describing whether the value of \fBCUDA_STANDARD\fP is a requirement. |
| .sp |
| If this property is set to \fBON\fP, then the value of the |
| \fBCUDA_STANDARD\fP target property is treated as a requirement. If this |
| property is \fBOFF\fP or unset, the \fBCUDA_STANDARD\fP target property is |
| treated as optional and may "decay" to a previous standard if the requested is |
| not available. For compilers that have no notion of a standard level, such as |
| MSVC 1800 (Visual Studio 2013) and lower, this has no effect. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_CUDA_STANDARD_REQUIRED\fP variable if it is set when a |
| target is created. |
| .SS CXX_EXTENSIONS |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Boolean specifying whether compiler specific extensions are requested. |
| .sp |
| This property specifies whether compiler specific extensions should be |
| used. For some compilers, this results in adding a flag such |
| as \fB\-std=gnu++11\fP instead of \fB\-std=c++11\fP to the compile line. This |
| property is \fBON\fP by default. The basic C++ standard level is |
| controlled by the \fBCXX_STANDARD\fP target property. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_CXX_EXTENSIONS\fP variable if set when a target is created |
| and otherwise by the value of |
| \fBCMAKE_CXX_EXTENSIONS_DEFAULT\fP (see |
| \fBCMP0128\fP). |
| .SS CXX_STANDARD |
| .sp |
| New in version 3.1. |
| |
| .sp |
| The C++ standard whose features are requested to build this target. |
| .sp |
| This property specifies the C++ standard whose features are requested |
| to build this target. For some compilers, this results in adding a |
| flag such as \fB\-std=gnu++11\fP to the compile line. For compilers that |
| have no notion of a standard level, such as Microsoft Visual C++ before |
| 2015 Update 3, this has no effect. |
| .sp |
| Supported values are: |
| .INDENT 0.0 |
| .TP |
| .B \fB98\fP |
| C++98 |
| .TP |
| .B \fB11\fP |
| C++11 |
| .TP |
| .B \fB14\fP |
| C++14 |
| .TP |
| .B \fB17\fP |
| New in version 3.8. |
| |
| .sp |
| C++17 |
| .TP |
| .B \fB20\fP |
| New in version 3.12. |
| |
| .sp |
| C++20 |
| .TP |
| .B \fB23\fP |
| New in version 3.20. |
| |
| .sp |
| C++23 |
| .UNINDENT |
| .sp |
| If the value requested does not result in a compile flag being added for |
| the compiler in use, a previous standard flag will be added instead. This |
| means that using: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET tgt PROPERTY CXX_STANDARD 11) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| with a compiler which does not support \fB\-std=gnu++11\fP or an equivalent |
| flag will not result in an error or warning, but will instead add the |
| \fB\-std=gnu++98\fP flag if supported. This "decay" behavior may be controlled |
| with the \fBCXX_STANDARD_REQUIRED\fP target property. |
| Additionally, the \fBCXX_EXTENSIONS\fP target property may be used to |
| control whether compiler\-specific extensions are enabled on a per\-target basis. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_CXX_STANDARD\fP variable if it is set when a target |
| is created. |
| .SS CXX_STANDARD_REQUIRED |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Boolean describing whether the value of \fBCXX_STANDARD\fP is a requirement. |
| .sp |
| If this property is set to \fBON\fP, then the value of the |
| \fBCXX_STANDARD\fP target property is treated as a requirement. If this |
| property is \fBOFF\fP or unset, the \fBCXX_STANDARD\fP target property is |
| treated as optional and may "decay" to a previous standard if the requested is |
| not available. For compilers that have no notion of a standard level, such as |
| MSVC 1800 (Visual Studio 2013) and lower, this has no effect. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_CXX_STANDARD_REQUIRED\fP variable if it is set when a |
| target is created. |
| .SS DEBUG_POSTFIX |
| .sp |
| See target property \fB<CONFIG>_POSTFIX\fP\&. |
| .sp |
| This property is a special case of the more\-general \fB<CONFIG>_POSTFIX\fP |
| property for the \fBDEBUG\fP configuration. |
| .SS DEFINE_SYMBOL |
| .sp |
| Define a symbol when compiling this target\(aqs sources. |
| .sp |
| \fBDEFINE_SYMBOL\fP sets the name of the preprocessor symbol defined when |
| compiling sources in a shared library. If not set here then it is set |
| to \fBtarget_EXPORTS\fP by default (with some substitutions if the target is |
| not a valid C identifier). This is useful for headers to know whether |
| they are being included from inside their library or outside to |
| properly setup dllexport/dllimport decorations. |
| .SS DEPLOYMENT_ADDITIONAL_FILES |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Set the WinCE project \fBAdditionalFiles\fP in \fBDeploymentTool\fP in \fB\&.vcproj\fP |
| files generated by the \fBVisual Studio 9 2008\fP generator. |
| This is useful when you want to debug on remote WinCE device. |
| Specify additional files that will be copied to the device. |
| For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET ${TARGET} PROPERTY |
| DEPLOYMENT_ADDITIONAL_FILES "english.lng|local_folder|remote_folder|0" |
| "german.lng|local_folder|remote_folder|0") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| produces: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| <DeploymentTool AdditionalFiles="english.lng|local_folder|remote_folder|0;german.lng|local_folder|remote_folder|0" ... /> |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS DEPLOYMENT_REMOTE_DIRECTORY |
| .sp |
| New in version 3.6. |
| |
| .sp |
| Set the WinCE project \fBRemoteDirectory\fP in \fBDeploymentTool\fP and |
| \fBRemoteExecutable\fP in \fBDebuggerTool\fP in \fB\&.vcproj\fP files generated |
| by the \fBVisual Studio 9 2008\fP generator. |
| This is useful when you want to debug on remote WinCE device. |
| For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET ${TARGET} PROPERTY |
| DEPLOYMENT_REMOTE_DIRECTORY "\e\eFlashStorage") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| produces: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| <DeploymentTool RemoteDirectory="\eFlashStorage" ... /> |
| <DebuggerTool RemoteExecutable="\eFlashStorage\etarget_file" ... /> |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS DEPRECATION |
| .sp |
| New in version 3.17. |
| |
| .sp |
| Deprecation message from imported target\(aqs developer. |
| .sp |
| \fBDEPRECATION\fP is the message regarding a deprecation status to be displayed |
| to downstream users of a target. |
| .sp |
| The message is formatted as follows: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| Lines that do not start in whitespace are wrapped as paragraph text. |
| .IP \(bu 2 |
| Lines that start in whitespace are preserved as preformatted text. |
| .UNINDENT |
| .SS DISABLE_PRECOMPILE_HEADERS |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Disables the precompilation of header files specified by |
| \fBPRECOMPILE_HEADERS\fP property. |
| .sp |
| If the property is not set, CMake will use the value provided |
| by \fBCMAKE_DISABLE_PRECOMPILE_HEADERS\fP\&. |
| .SS DOTNET_SDK |
| .sp |
| New in version 3.23. |
| |
| .sp |
| Specify the .NET SDK for C# projects. For example: \fBMicrosoft.NET.Sdk\fP\&. |
| .sp |
| This property tells Visual Studio Generators for VS 2019 and |
| above to generate a .NET SDK\-style project using the specified SDK. |
| The property is meaningful only to these generators, and only in C# |
| targets. It is ignored for C++ projects, even if they are managed |
| (e.g. using \fBCOMMON_LANGUAGE_RUNTIME\fP). |
| .sp |
| This property must be a non\-empty string to generate .NET SDK\-style projects. |
| CMake does not perform any validations for the value of the property. |
| .sp |
| This property may be initialized for all targets using the |
| \fBCMAKE_DOTNET_SDK\fP variable. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The Visual Studio Generators in this version of CMake have not |
| yet learned to support \fBadd_custom_command()\fP in .NET SDK\-style |
| projects. It is currently an error to attach a custom command to a |
| target with the \fBDOTNET_SDK\fP property set. |
| .UNINDENT |
| .UNINDENT |
| .SS DOTNET_TARGET_FRAMEWORK |
| .sp |
| New in version 3.17. |
| |
| .sp |
| Specify the .NET target framework. |
| .sp |
| Used to specify the .NET target framework for C++/CLI and C#. For |
| example: \fBnetcoreapp2.1\fP\&. |
| .sp |
| This property is only evaluated for Visual Studio Generators |
| VS 2010 and above. |
| .sp |
| Can be initialized for all targets using the variable |
| \fBCMAKE_DOTNET_TARGET_FRAMEWORK\fP\&. |
| .SS DOTNET_TARGET_FRAMEWORK_VERSION |
| .sp |
| New in version 3.12. |
| |
| .sp |
| Specify the .NET target framework version. |
| .sp |
| Used to specify the .NET target framework version for C++/CLI and C#. |
| For example: \fBv4.5\fP\&. |
| .sp |
| This property is only evaluated for Visual Studio Generators |
| VS 2010 and above. |
| .sp |
| To initialize this variable for all targets set |
| \fBCMAKE_DOTNET_TARGET_FRAMEWORK\fP or |
| \fBCMAKE_DOTNET_TARGET_FRAMEWORK_VERSION\fP\&. If both are set, |
| the latter is ignored. |
| .SS EchoString |
| .sp |
| A message to be displayed when the target is built. |
| .sp |
| A message to display on some generators (such as Makefile Generators) |
| when the target is built. |
| .SS ENABLE_EXPORTS |
| .sp |
| Specify whether an executable exports symbols for loadable modules. |
| .sp |
| Normally an executable does not export any symbols because it is the |
| final program. It is possible for an executable to export symbols to |
| be used by loadable modules. When this property is set to true CMake |
| will allow other targets to "link" to the executable with the |
| \fBtarget_link_libraries()\fP command. On all platforms a target\-level |
| dependency on the executable is created for targets that link to it. |
| Handling of the executable on the link lines of the loadable modules |
| varies by platform: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| On Windows\-based systems (including Cygwin) an "import library" is |
| created along with the executable to list the exported symbols. |
| Loadable modules link to the import library to get the symbols. |
| .IP \(bu 2 |
| On macOS, loadable modules link to the executable itself using the |
| \fB\-bundle_loader\fP flag. |
| .IP \(bu 2 |
| On AIX, a linker "import file" is created along with the executable |
| to list the exported symbols for import when linking other targets. |
| Loadable modules link to the import file to get the symbols. |
| .IP \(bu 2 |
| On other platforms, loadable modules are simply linked without |
| referencing the executable since the dynamic loader will |
| automatically bind symbols when the module is loaded. |
| .UNINDENT |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_ENABLE_EXPORTS\fP if it is set when a target is created. |
| .SS EXCLUDE_FROM_ALL |
| .sp |
| Set this target property to a true (or false) value to exclude (or include) |
| the target from the "all" target of the containing directory and its |
| ancestors. If excluded, running e.g. \fBmake\fP in the containing directory |
| or its ancestors will not build the target by default. |
| .sp |
| If this target property is not set then the target will be included in |
| the "all" target of the containing directory. Furthermore, it will be |
| included in the "all" target of its ancestor directories unless the |
| \fBEXCLUDE_FROM_ALL\fP directory property is set. |
| .sp |
| With \fBEXCLUDE_FROM_ALL\fP set to false or not set at all, the target |
| will be brought up to date as part of doing a \fBmake install\fP or its |
| equivalent for the CMake generator being used. |
| .sp |
| If a target has \fBEXCLUDE_FROM_ALL\fP set to true, it may still be listed |
| in an \fBinstall(TARGETS)\fP command, but the user is responsible for |
| ensuring that the target\(aqs build artifacts are not missing or outdated when |
| an install is performed. |
| .sp |
| This property may use "generator expressions" with the syntax \fB$<...>\fP\&. See |
| the \fBcmake\-generator\-expressions(7)\fP manual for available expressions. |
| .sp |
| Only the "Ninja Multi\-Config" generator supports a property value that varies by |
| configuration. For all other generators the value of this property must be the |
| same for all configurations. |
| .SS EXCLUDE_FROM_DEFAULT_BUILD |
| .sp |
| Exclude target from \fBBuild Solution\fP\&. |
| .sp |
| This property is only used by Visual Studio generators. |
| When set to \fBTRUE\fP, the target will not be built when you press |
| \fBBuild Solution\fP\&. |
| .SS EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG> |
| .sp |
| Per\-configuration version of target exclusion from \fBBuild Solution\fP\&. |
| .sp |
| This is the configuration\-specific version of |
| \fBEXCLUDE_FROM_DEFAULT_BUILD\fP\&. If the generic |
| \fBEXCLUDE_FROM_DEFAULT_BUILD\fP is also set on a target, |
| \fBEXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>\fP takes |
| precedence in configurations for which it has a value. |
| .SS EXPORT_COMPILE_COMMANDS |
| .sp |
| New in version 3.20. |
| |
| .sp |
| Enable/Disable output of compile commands during generation for a target. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_EXPORT_COMPILE_COMMANDS\fP if it is set when a target is created. |
| .SS EXPORT_NAME |
| .sp |
| Exported name for target files. |
| .sp |
| This sets the name for the \fBIMPORTED\fP target generated by the |
| \fBinstall(EXPORT)\fP and \fBexport()\fP commands. |
| If not set, the logical target name is used by default. |
| .SS EXPORT_PROPERTIES |
| .sp |
| New in version 3.12. |
| |
| .sp |
| List additional properties to export for a target. |
| .sp |
| This property contains a list of property names that should be exported by |
| the \fBinstall(EXPORT)\fP and \fBexport()\fP commands. By default |
| only a limited number of properties are exported. This property can be used |
| to additionally export other properties as well. |
| .sp |
| Properties starting with \fBINTERFACE_\fP or \fBIMPORTED_\fP are not allowed as |
| they are reserved for internal CMake use. |
| .sp |
| Properties containing generator expressions are also not allowed. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Since CMake 3.19, Interface Libraries may have arbitrary |
| target properties. If a project exports an interface library |
| with custom properties, the resulting package may not work with |
| dependents configured by older versions of CMake that reject the |
| custom properties. |
| .UNINDENT |
| .UNINDENT |
| .SS FOLDER |
| .sp |
| Set the folder name. Use to organize targets in an IDE. |
| .sp |
| Targets with no \fBFOLDER\fP property will appear as top level entities in |
| IDEs like Visual Studio. Targets with the same \fBFOLDER\fP property value |
| will appear next to each other in a folder of that name. To nest |
| folders, use \fBFOLDER\fP values such as \(aqGUI/Dialogs\(aq with \(aq/\(aq characters |
| separating folder levels. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_FOLDER\fP if it is set when a target is created. |
| .SS Fortran_BUILDING_INSTRINSIC_MODULES |
| .sp |
| New in version 3.22. |
| |
| .sp |
| Instructs the CMake Fortran preprocessor that the target is building |
| Fortran intrinsics for building a Fortran compiler. |
| .sp |
| This property is off by default and should be turned only on projects |
| that build a Fortran compiler. It should not be turned on for projects |
| that use a Fortran compiler. |
| .sp |
| Turning this property on will correctly add dependencies for building |
| Fortran intrinsic modules whereas turning the property off will ignore |
| Fortran intrinsic modules in the dependency graph as they are supplied |
| by the compiler itself. |
| .SS Fortran_FORMAT |
| .sp |
| Set to \fBFIXED\fP or \fBFREE\fP to indicate the Fortran source layout. |
| .sp |
| This property tells CMake whether the Fortran source files in a target |
| use fixed\-format or free\-format. CMake will pass the corresponding |
| format flag to the compiler. Use the source\-specific \fBFortran_FORMAT\fP |
| property to change the format of a specific source file. If the |
| variable \fBCMAKE_Fortran_FORMAT\fP is set when a target is created its |
| value is used to initialize this property. |
| .SS Fortran_MODULE_DIRECTORY |
| .sp |
| Specify output directory for Fortran modules provided by the target. |
| .sp |
| If the target contains Fortran source files that provide modules and |
| the compiler supports a module output directory this specifies the |
| directory in which the modules will be placed. When this property is |
| not set the modules will be placed in the build directory |
| corresponding to the target\(aqs source directory. If the variable |
| \fBCMAKE_Fortran_MODULE_DIRECTORY\fP is set when a target is created its |
| value is used to initialize this property. |
| .sp |
| When using one of the Visual Studio Generators with the Intel Fortran |
| plugin installed in Visual Studio, a subdirectory named after the |
| configuration will be appended to the path where modules are created. |
| For example, if \fBFortran_MODULE_DIRECTORY\fP is set to \fBC:/some/path\fP, |
| modules will end up in \fBC:/some/path/Debug\fP (or |
| \fBC:/some/path/Release\fP etc.) when an Intel Fortran \fB\&.vfproj\fP file is |
| generated, and in \fBC:/some/path\fP when any other generator is used. |
| .sp |
| Note that some compilers will automatically search the module output |
| directory for modules USEd during compilation but others will not. If |
| your sources USE modules their location must be specified by |
| \fBINCLUDE_DIRECTORIES\fP regardless of this property. |
| .SS Fortran_PREPROCESS |
| .sp |
| New in version 3.18. |
| |
| .sp |
| Control whether the Fortran source file should be unconditionally |
| preprocessed. |
| .sp |
| If unset or empty, rely on the compiler to determine whether the file |
| should be preprocessed. If explicitly set to \fBOFF\fP then the file does not |
| need to be preprocessed. If explicitly set to \fBON\fP, then the file does |
| need to be preprocessed as part of the compilation step. |
| .sp |
| When using the \fBNinja\fP generator, all source files are |
| first preprocessed in order to generate module dependency |
| information. Setting this property to \fBOFF\fP will make \fBNinja\fP |
| skip this step. |
| .sp |
| Use the source\-specific \fBFortran_PREPROCESS\fP property if a single |
| file needs to be preprocessed. If the variable |
| \fBCMAKE_Fortran_PREPROCESS\fP is set when a target is created its |
| value is used to initialize this property. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| For some compilers, \fBNAG\fP, \fBPGI\fP and \fBSolaris Studio\fP, |
| setting this to \fBOFF\fP will have no effect. |
| .UNINDENT |
| .UNINDENT |
| .SS FRAMEWORK |
| .sp |
| Build \fBSHARED\fP or \fBSTATIC\fP library as Framework Bundle on the macOS and iOS. |
| .sp |
| If such a library target has this property set to \fBTRUE\fP it will be |
| built as a framework when built on the macOS and iOS. It will have the |
| directory structure required for a framework and will be suitable to |
| be used with the \fB\-framework\fP option. This property is initialized by the |
| value of the \fBCMAKE_FRAMEWORK\fP variable if it is set when a target is |
| created. |
| .sp |
| To customize \fBInfo.plist\fP file in the framework, use |
| \fBMACOSX_FRAMEWORK_INFO_PLIST\fP target property. |
| .sp |
| For macOS see also the \fBFRAMEWORK_VERSION\fP target property. |
| .sp |
| Example of creation \fBdynamicFramework\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(dynamicFramework SHARED |
| dynamicFramework.c |
| dynamicFramework.h |
| ) |
| set_target_properties(dynamicFramework PROPERTIES |
| FRAMEWORK TRUE |
| FRAMEWORK_VERSION C |
| MACOSX_FRAMEWORK_IDENTIFIER com.cmake.dynamicFramework |
| MACOSX_FRAMEWORK_INFO_PLIST Info.plist |
| # "current version" in semantic format in Mach\-O binary file |
| VERSION 16.4.0 |
| # "compatibility version" in semantic format in Mach\-O binary file |
| SOVERSION 1.0.0 |
| PUBLIC_HEADER dynamicFramework.h |
| XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY "iPhone Developer" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> |
| .sp |
| New in version 3.18. |
| |
| .sp |
| Postfix to append to the framework file name for configuration \fB<CONFIG>\fP, |
| when using a multi\-config generator (like Xcode and Ninja Multi\-Config). |
| .sp |
| When building with configuration \fB<CONFIG>\fP the value of this property |
| is appended to the framework file name built on disk. |
| .sp |
| For example, given a framework called \fBmy_fw\fP, a value of \fB_debug\fP |
| for the \fBFRAMEWORK_MULTI_CONFIG_POSTFIX_DEBUG\fP property, and |
| \fBDebug;Release\fP in \fBCMAKE_CONFIGURATION_TYPES\fP, the following |
| relevant files would be created for the \fBDebug\fP and \fBRelease\fP |
| configurations: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBRelease/my_fw.framework/my_fw\fP |
| .IP \(bu 2 |
| \fBRelease/my_fw.framework/Versions/A/my_fw\fP |
| .IP \(bu 2 |
| \fBDebug/my_fw.framework/my_fw_debug\fP |
| .IP \(bu 2 |
| \fBDebug/my_fw.framework/Versions/A/my_fw_debug\fP |
| .UNINDENT |
| .sp |
| For framework targets, this property is initialized by the value of the |
| \fBCMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>\fP variable if it |
| is set when a target is created. |
| .sp |
| This property is ignored for non\-framework targets, and when using single |
| config generators. |
| .SS FRAMEWORK_VERSION |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Version of a framework created using the \fBFRAMEWORK\fP target |
| property (e.g. \fBA\fP). |
| .sp |
| This property only affects macOS, as iOS doesn\(aqt have versioned |
| directory structure. |
| .SS GENERATOR_FILE_NAME |
| .sp |
| Generator\(aqs file for this target. |
| .sp |
| An internal property used by some generators to record the name of the |
| project or dsp file associated with this target. Note that at |
| configure time, this property is only set for targets created by |
| \fBinclude_external_msproject()\fP\&. |
| .SS GHS_INTEGRITY_APP |
| .sp |
| New in version 3.14. |
| |
| .sp |
| \fBON\fP / \fBOFF\fP boolean to determine if an executable target should |
| be treated as an \fIIntegrity Application\fP\&. |
| .sp |
| If no value is set and if a \fB\&.int\fP file is added as a source file to the |
| executable target it will be treated as an \fIIntegrity Application\fP\&. |
| .sp |
| Supported on \fBGreen Hills MULTI\fP\&. |
| .SS GHS_NO_SOURCE_GROUP_FILE |
| .sp |
| New in version 3.14. |
| |
| .sp |
| \fBON\fP / \fBOFF\fP boolean to control if the project file for a target should |
| be one single file or multiple files. |
| .sp |
| The default behavior or when the property is \fBOFF\fP is to generate a project |
| file for the target and then a sub\-project file for each source group. |
| .sp |
| When this property is \fBON\fP or if \fBCMAKE_GHS_NO_SOURCE_GROUP_FILE\fP |
| is \fBON\fP then only a single project file is generated for the target. |
| .sp |
| Supported on \fBGreen Hills MULTI\fP\&. |
| .SS GNUtoMS |
| .sp |
| Convert GNU import library (\fB\&.dll.a\fP) to MS format (\fB\&.lib\fP). |
| .sp |
| When linking a shared library or executable that exports symbols using |
| GNU tools on Windows (MinGW/MSYS) with Visual Studio installed convert |
| the import library (\fB\&.dll.a\fP) from GNU to MS format (\fB\&.lib\fP). Both import |
| libraries will be installed by \fBinstall(TARGETS)\fP and exported by |
| \fBinstall(EXPORT)\fP and \fBexport()\fP to be linked |
| by applications with either GNU\- or MS\-compatible tools. |
| .sp |
| If the variable \fBCMAKE_GNUtoMS\fP is set when a target is created its |
| value is used to initialize this property. The variable must be set |
| prior to the first command that enables a language such as \fBproject()\fP |
| or \fBenable_language()\fP\&. CMake provides the variable as an option to the |
| user automatically when configuring on Windows with GNU tools. |
| .SS HAS_CXX |
| .sp |
| Link the target using the C++ linker tool (obsolete). |
| .sp |
| This is equivalent to setting the \fBLINKER_LANGUAGE\fP |
| property to \fBCXX\fP\&. |
| .SS HEADER_DIRS |
| .sp |
| New in version 3.23. |
| |
| .sp |
| Semicolon\-separated list of base directories of the target\(aqs default |
| header set (i.e. the file set with name and type \fBHEADERS\fP). The property |
| supports \fBgenerator expressions\fP\&. |
| .sp |
| This property is normally only set by \fBtarget_sources(FILE_SET)\fP |
| rather than being manipulated directly. |
| .sp |
| See \fBHEADER_DIRS_<NAME>\fP for the list of base directories in |
| other header sets. |
| .SS HEADER_DIRS_<NAME> |
| .sp |
| New in version 3.23. |
| |
| .sp |
| Semicolon\-separated list of base directories of the target\(aqs \fB<NAME>\fP |
| header set, which has the set type \fBHEADERS\fP\&. The property supports |
| \fBgenerator expressions\fP\&. |
| .sp |
| This property is normally only set by \fBtarget_sources(FILE_SET)\fP |
| rather than being manipulated directly. |
| .sp |
| See \fBHEADER_DIRS\fP for the list of base directories in the |
| default header set. See \fBHEADER_SETS\fP for the file set names of all |
| header sets. |
| .SS HEADER_SET |
| .sp |
| New in version 3.23. |
| |
| .sp |
| Semicolon\-separated list of files in the target\(aqs default header set, |
| (i.e. the file set with name and type \fBHEADERS\fP). If any of the paths |
| are relative, they are computed relative to the target\(aqs source directory. |
| The property supports |
| \fBgenerator expressions\fP\&. |
| .sp |
| This property is normally only set by \fBtarget_sources(FILE_SET)\fP |
| rather than being manipulated directly. |
| .sp |
| See \fBHEADER_SET_<NAME>\fP for the list of files in other header sets. |
| .SS HEADER_SET_<NAME> |
| .sp |
| New in version 3.23. |
| |
| .sp |
| Semicolon\-separated list of files in the target\(aqs \fB<NAME>\fP header set, |
| which has the set type \fBHEADERS\fP\&. If any of the paths are relative, |
| they are computed relative to the target\(aqs source directory. The property |
| supports \fBgenerator expressions\fP\&. |
| .sp |
| This property is normally only set by \fBtarget_sources(FILE_SET)\fP |
| rather than being manipulated directly. |
| .sp |
| See \fBHEADER_SET\fP for the list of files in the default header set. |
| See \fBHEADER_SETS\fP for the file set names of all header sets. |
| .SS HEADER_SETS |
| .sp |
| New in version 3.23. |
| |
| .sp |
| Read\-only list of the target\(aqs \fBPRIVATE\fP and \fBPUBLIC\fP header sets (i.e. |
| all file sets with the type \fBHEADERS\fP). Files listed in these file sets are |
| treated as source files for the purpose of IDE integration. The files also |
| have their \fBHEADER_FILE_ONLY\fP property set to \fBTRUE\fP\&. |
| .sp |
| Header sets may be defined using the \fBtarget_sources()\fP command |
| \fBFILE_SET\fP option with type \fBHEADERS\fP\&. |
| .sp |
| See also \fBHEADER_SET_<NAME>\fP, \fBHEADER_SET\fP and |
| \fBINTERFACE_HEADER_SETS\fP\&. |
| .SS HIP_ARCHITECTURES |
| .sp |
| New in version 3.21. |
| |
| .sp |
| List of AMD GPU architectures to generate device code for. |
| .sp |
| A non\-empty false value (e.g. \fBOFF\fP) disables adding architectures. |
| This is intended to support packagers and rare cases where full control |
| over the passed flags is required. |
| .sp |
| This property is initialized by the value of the \fBCMAKE_HIP_ARCHITECTURES\fP |
| variable if it is set when a target is created. |
| .sp |
| The HIP compilation model has two modes: whole and separable. Whole compilation |
| generates device code at compile time. Separable compilation generates device |
| code at link time. Therefore the \fBHIP_ARCHITECTURES\fP target property should |
| be set on targets that compile or link with any HIP sources. |
| .SS Examples |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET tgt PROPERTY HIP_ARCHITECTURES gfx801 gfx900) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Generates code for both \fBgfx801\fP and \fBgfx900\fP\&. |
| .SS HIP_EXTENSIONS |
| .sp |
| New in version 3.21. |
| |
| .sp |
| Boolean specifying whether compiler specific extensions are requested. |
| .sp |
| This property specifies whether compiler specific extensions should be |
| used. For some compilers, this results in adding a flag such |
| as \fB\-std=gnu++11\fP instead of \fB\-std=c++11\fP to the compile line. This |
| property is \fBON\fP by default. The basic HIP/C++ standard level is |
| controlled by the \fBHIP_STANDARD\fP target property. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_HIP_EXTENSIONS\fP variable if set when a target is created |
| and otherwise by the value of |
| \fBCMAKE_HIP_EXTENSIONS_DEFAULT\fP (see |
| \fBCMP0128\fP). |
| .SS HIP_STANDARD |
| .sp |
| New in version 3.21. |
| |
| .sp |
| The HIP/C++ standard requested to build this target. |
| .sp |
| Supported values are: |
| .INDENT 0.0 |
| .TP |
| .B \fB98\fP |
| HIP C++98 |
| .TP |
| .B \fB11\fP |
| HIP C++11 |
| .TP |
| .B \fB14\fP |
| HIP C++14 |
| .TP |
| .B \fB17\fP |
| HIP C++17 |
| .TP |
| .B \fB20\fP |
| HIP C++20 |
| .TP |
| .B \fB23\fP |
| HIP C++23 |
| .UNINDENT |
| .sp |
| If the value requested does not result in a compile flag being added for |
| the compiler in use, a previous standard flag will be added instead. This |
| means that using: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET tgt PROPERTY HIP_STANDARD 11) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| with a compiler which does not support \fB\-std=gnu++11\fP or an equivalent |
| flag will not result in an error or warning, but will instead add the |
| \fB\-std=gnu++98\fP flag if supported. This "decay" behavior may be controlled |
| with the \fBHIP_STANDARD_REQUIRED\fP target property. |
| Additionally, the \fBHIP_EXTENSIONS\fP target property may be used to |
| control whether compiler\-specific extensions are enabled on a per\-target basis. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_HIP_STANDARD\fP variable if it is set when a target |
| is created. |
| .SS HIP_STANDARD_REQUIRED |
| .sp |
| New in version 3.21. |
| |
| .sp |
| Boolean describing whether the value of \fBHIP_STANDARD\fP is a requirement. |
| .sp |
| If this property is set to \fBON\fP, then the value of the |
| \fBHIP_STANDARD\fP target property is treated as a requirement. If this |
| property is \fBOFF\fP or unset, the \fBHIP_STANDARD\fP target property is |
| treated as optional and may "decay" to a previous standard if the requested is |
| not available. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_HIP_STANDARD_REQUIRED\fP variable if it is set when a |
| target is created. |
| .SS IMPLICIT_DEPENDS_INCLUDE_TRANSFORM |
| .sp |
| Specify \fB#include\fP line transforms for dependencies in a target. |
| .sp |
| This property specifies rules to transform macro\-like \fB#include\fP lines |
| during implicit dependency scanning of C and C++ source files. The |
| list of rules must be semicolon\-separated with each entry of the form |
| \fBA_MACRO(%)=value\-with\-%\fP (the \fB%\fP must be literal). During dependency |
| scanning occurrences of \fBA_MACRO(...)\fP on \fB#include\fP lines will be |
| replaced by the value given with the macro argument substituted for |
| \fB%\fP\&. For example, the entry |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| MYDIR(%)=<mydir/%> |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| will convert lines of the form |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #include MYDIR(myheader.h) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| to |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #include <mydir/myheader.h> |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| allowing the dependency to be followed. |
| .sp |
| This property applies to sources in the target on which it is set. |
| .SS IMPORTED |
| .sp |
| Read\-only indication of whether a target is \fBIMPORTED\fP\&. |
| .sp |
| The boolean value of this property is \fBTrue\fP for targets created with |
| the \fBIMPORTED\fP option to \fBadd_executable()\fP or \fBadd_library()\fP\&. |
| It is \fBFalse\fP for targets built within the project. |
| .SS IMPORTED_COMMON_LANGUAGE_RUNTIME |
| .sp |
| New in version 3.12. |
| |
| .sp |
| Property to define if the target uses \fBC++/CLI\fP\&. |
| .sp |
| Ignored for non\-imported targets. |
| .sp |
| See also the \fBCOMMON_LANGUAGE_RUNTIME\fP target property. |
| .SS IMPORTED_CONFIGURATIONS |
| .sp |
| Configurations provided for an IMPORTED target. |
| .sp |
| Set this to the list of configuration names available for an IMPORTED |
| target. The names correspond to configurations defined in the project |
| from which the target is imported. If the importing project uses a |
| different set of configurations the names may be mapped using the |
| MAP_IMPORTED_CONFIG_<CONFIG> property. Ignored for non\-imported |
| targets. |
| .SS IMPORTED_GLOBAL |
| .sp |
| New in version 3.11. |
| |
| .sp |
| Indication of whether an IMPORTED target is |
| globally visible. |
| .sp |
| The boolean value of this property is True for targets created with the |
| \fBIMPORTED\fP \fBGLOBAL\fP options to \fBadd_executable()\fP or |
| \fBadd_library()\fP\&. It is always False for targets built within the |
| project. |
| .sp |
| For targets created with the \fBIMPORTED\fP option to |
| \fBadd_executable()\fP or \fBadd_library()\fP but without the |
| additional option \fBGLOBAL\fP this is False, too. However, setting this |
| property for such a locally \fBIMPORTED\fP target to True promotes that |
| target to global scope. This promotion can only be done in the same |
| directory where that \fBIMPORTED\fP target was created in the first place. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Once an imported target has been made global, it cannot be changed back to |
| non\-global. Therefore, if a project sets this property, it may only |
| provide a value of True. CMake will issue an error if the project tries to |
| set the property to a non\-True value, even if the value was already False. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Local ALIAS targets created before promoting an |
| IMPORTED target from \fBLOCAL\fP to \fBGLOBAL\fP, keep |
| their initial scope (see \fBALIAS_GLOBAL\fP target property). |
| .UNINDENT |
| .UNINDENT |
| .SS IMPORTED_IMPLIB |
| .sp |
| Full path to the import library for an \fBIMPORTED\fP target. |
| .sp |
| Set this to the location of the \fB\&.lib\fP part of a Windows DLL, or on |
| AIX set it to an import file created for executables that export symbols |
| (see the \fBENABLE_EXPORTS\fP target property). |
| Ignored for non\-imported targets. |
| .SS IMPORTED_IMPLIB_<CONFIG> |
| .sp |
| <CONFIG>\-specific version of \fBIMPORTED_IMPLIB\fP property. |
| .sp |
| Configuration names correspond to those provided by the project from |
| which the target is imported. |
| .SS IMPORTED_LIBNAME |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Specify the link library name for an imported |
| Interface Library\&. |
| .sp |
| An interface library builds no library file itself but does specify |
| usage requirements for its consumers. The \fBIMPORTED_LIBNAME\fP |
| property may be set to specify a single library name to be placed |
| on the link line in place of the interface library target name as |
| a requirement for using the interface. |
| .sp |
| This property is intended for use in naming libraries provided by |
| a platform SDK for which the full path to a library file may not |
| be known. The value may be a plain library name such as \fBfoo\fP |
| but may \fInot\fP be a path (e.g. \fB/usr/lib/libfoo.so\fP) or a flag |
| (e.g. \fB\-Wl,...\fP). The name is never treated as a library target |
| name even if it happens to name one. |
| .sp |
| The \fBIMPORTED_LIBNAME\fP property is allowed only on |
| imported Interface Libraries |
| and is rejected on targets of other types (for which |
| the \fBIMPORTED_LOCATION\fP target property may be used). |
| .SS IMPORTED_LIBNAME_<CONFIG> |
| .sp |
| New in version 3.8. |
| |
| .sp |
| <CONFIG>\-specific version of \fBIMPORTED_LIBNAME\fP property. |
| .sp |
| Configuration names correspond to those provided by the project from |
| which the target is imported. |
| .SS IMPORTED_LINK_DEPENDENT_LIBRARIES |
| .sp |
| Dependent shared libraries of an imported shared library. |
| .sp |
| Shared libraries may be linked to other shared libraries as part of |
| their implementation. On some platforms the linker searches for the |
| dependent libraries of shared libraries they are including in the |
| link. Set this property to the list of dependent shared libraries of |
| an imported library. The list should be disjoint from the list of |
| interface libraries in the \fBINTERFACE_LINK_LIBRARIES\fP property. On |
| platforms requiring dependent shared libraries to be found at link |
| time CMake uses this list to add appropriate files or paths to the |
| link command line. Ignored for non\-imported targets. |
| .SS IMPORTED_LINK_DEPENDENT_LIBRARIES_<CONFIG> |
| .sp |
| <CONFIG>\-specific version of \fBIMPORTED_LINK_DEPENDENT_LIBRARIES\fP\&. |
| .sp |
| Configuration names correspond to those provided by the project from |
| which the target is imported. If set, this property completely |
| overrides the generic property for the named configuration. |
| .SS IMPORTED_LINK_INTERFACE_LANGUAGES |
| .sp |
| Languages compiled into an \fBIMPORTED\fP static library. |
| .sp |
| Set this to the list of languages of source files compiled to produce |
| a \fBSTATIC IMPORTED\fP library (such as \fBC\fP or \fBCXX\fP). CMake accounts for |
| these languages when computing how to link a target to the imported |
| library. For example, when a C executable links to an imported C++ |
| static library CMake chooses the C++ linker to satisfy language |
| runtime dependencies of the static library. |
| .sp |
| This property is ignored for targets that are not \fBSTATIC\fP libraries. |
| This property is ignored for non\-imported targets. |
| .SS IMPORTED_LINK_INTERFACE_LANGUAGES_<CONFIG> |
| .sp |
| <CONFIG>\-specific version of \fBIMPORTED_LINK_INTERFACE_LANGUAGES\fP\&. |
| .sp |
| Configuration names correspond to those provided by the project from |
| which the target is imported. If set, this property completely |
| overrides the generic property for the named configuration. |
| .SS IMPORTED_LINK_INTERFACE_LIBRARIES |
| .sp |
| Transitive link interface of an \fBIMPORTED\fP target. |
| .sp |
| Set this to the list of libraries whose interface is included when an |
| \fBIMPORTED\fP library target is linked to another target. The libraries |
| will be included on the link line for the target. Unlike the |
| \fBLINK_INTERFACE_LIBRARIES\fP property, this property applies to all |
| imported target types, including \fBSTATIC\fP libraries. This property is |
| ignored for non\-imported targets. |
| .sp |
| This property is ignored if the target also has a non\-empty |
| \fBINTERFACE_LINK_LIBRARIES\fP property. |
| .sp |
| This property is deprecated. Use \fBINTERFACE_LINK_LIBRARIES\fP instead. |
| .SS IMPORTED_LINK_INTERFACE_LIBRARIES_<CONFIG> |
| .sp |
| <CONFIG>\-specific version of \fBIMPORTED_LINK_INTERFACE_LIBRARIES\fP\&. |
| .sp |
| Configuration names correspond to those provided by the project from |
| which the target is imported. If set, this property completely |
| overrides the generic property for the named configuration. |
| .sp |
| This property is ignored if the target also has a non\-empty |
| \fBINTERFACE_LINK_LIBRARIES\fP property. |
| .sp |
| This property is deprecated. Use \fBINTERFACE_LINK_LIBRARIES\fP instead. |
| .SS IMPORTED_LINK_INTERFACE_MULTIPLICITY |
| .sp |
| Repetition count for cycles of \fBIMPORTED\fP static libraries. |
| .sp |
| This is \fBLINK_INTERFACE_MULTIPLICITY\fP for \fBIMPORTED\fP targets. |
| .SS IMPORTED_LINK_INTERFACE_MULTIPLICITY_<CONFIG> |
| .sp |
| <CONFIG>\-specific version of \fBIMPORTED_LINK_INTERFACE_MULTIPLICITY\fP\&. |
| .sp |
| If set, this property completely overrides the generic property for |
| the named configuration. |
| .SS IMPORTED_LOCATION |
| .sp |
| Full path to the main file on disk for an \fBIMPORTED\fP target. |
| .sp |
| Set this to the location of an \fBIMPORTED\fP target file on disk. For |
| executables this is the location of the executable file. For \fBSTATIC\fP |
| libraries and modules this is the location of the library or module. |
| For \fBSHARED\fP libraries on non\-DLL platforms this is the location of the |
| shared library. For application bundles on macOS this is the location of |
| the executable file inside \fBContents/MacOS\fP within the bundle folder. |
| For frameworks on macOS this is the location of the |
| library file symlink just inside the framework folder. For DLLs this |
| is the location of the \fB\&.dll\fP part of the library. For \fBUNKNOWN\fP |
| libraries this is the location of the file to be linked. Ignored for |
| non\-imported targets. |
| .sp |
| The \fBIMPORTED_LOCATION\fP target property may be overridden for a |
| given configuration \fB<CONFIG>\fP by the configuration\-specific |
| \fBIMPORTED_LOCATION_<CONFIG>\fP target property. Furthermore, |
| the \fBMAP_IMPORTED_CONFIG_<CONFIG>\fP target property may be |
| used to map between a project\(aqs configurations and those of an imported |
| target. If none of these is set then the name of any other configuration |
| listed in the \fBIMPORTED_CONFIGURATIONS\fP target property may be |
| selected and its \fBIMPORTED_LOCATION_<CONFIG>\fP value used. |
| .sp |
| To get the location of an imported target read one of the \fBLOCATION\fP |
| or \fBLOCATION_<CONFIG>\fP properties. |
| .sp |
| For platforms with import libraries (e.g. Windows) see also |
| \fBIMPORTED_IMPLIB\fP\&. |
| .SS IMPORTED_LOCATION_<CONFIG> |
| .sp |
| <CONFIG>\-specific version of \fBIMPORTED_LOCATION\fP property. |
| .sp |
| Configuration names correspond to those provided by the project from |
| which the target is imported. |
| .SS IMPORTED_NO_SONAME |
| .sp |
| Specifies that an \fBIMPORTED\fP shared library target has no \fBsoname\fP\&. |
| .sp |
| Set this property to true for an imported shared library file that has |
| no \fBsoname\fP field. CMake may adjust generated link commands for some |
| platforms to prevent the linker from using the path to the library in |
| place of its missing \fBsoname\fP\&. Ignored for non\-imported targets. |
| .SS IMPORTED_NO_SONAME_<CONFIG> |
| .sp |
| <CONFIG>\-specific version of \fBIMPORTED_NO_SONAME\fP property. |
| .sp |
| Configuration names correspond to those provided by the project from |
| which the target is imported. |
| .SS IMPORTED_NO_SYSTEM |
| .sp |
| New in version 3.23. |
| |
| .sp |
| Specifies that an Imported Target is not |
| a \fBSYSTEM\fP library. This has the following effects: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| Entries of \fBINTERFACE_INCLUDE_DIRECTORIES\fP are not treated |
| as \fBSYSTEM\fP include directories when compiling consumers, as they |
| would be by default. Entries of |
| \fBINTERFACE_SYSTEM_INCLUDE_DIRECTORIES\fP are not affected, |
| and will always be treated as \fBSYSTEM\fP include directories. |
| .UNINDENT |
| .sp |
| This property can also be enabled on a non\-imported target. Doing so does |
| not affect the build system, but does tell the \fBinstall(EXPORT)\fP and |
| \fBexport()\fP commands to enable it on the imported targets they generate. |
| .sp |
| See the \fBNO_SYSTEM_FROM_IMPORTED\fP target property to set this |
| behavior on the target consuming the include directories rather than |
| providing them. |
| .SS IMPORTED_OBJECTS |
| .sp |
| New in version 3.9. |
| |
| .sp |
| A semicolon\-separated list of absolute paths |
| to the object files on disk for an imported |
| object library\&. |
| .sp |
| Ignored for non\-imported targets. |
| .sp |
| Projects may skip \fBIMPORTED_OBJECTS\fP if the configuration\-specific |
| property \fBIMPORTED_OBJECTS_<CONFIG>\fP is set instead, except in |
| situations as noted in the section below. |
| .SS Xcode Generator Considerations |
| .sp |
| New in version 3.20. |
| |
| .sp |
| For Apple platforms, a project may be built for more than one architecture. |
| This is controlled by the \fBCMAKE_OSX_ARCHITECTURES\fP variable. |
| For all but the \fBXcode\fP generator, CMake invokes compilers once |
| per source file and passes multiple \fB\-arch\fP flags, leading to a single |
| object file which will be a universal binary. Such object files work well |
| when listed in the \fBIMPORTED_OBJECTS\fP of a separate CMake build, even for |
| the \fBXcode\fP generator. But producing such object files with the |
| \fBXcode\fP generator is more difficult, since it invokes the compiler |
| once per architecture for each source file. Unlike the other generators, |
| it does not generate universal object file binaries. |
| .sp |
| A further complication with the \fBXcode\fP generator is that when |
| targeting device platforms (iOS, tvOS or watchOS), the \fBXcode\fP |
| generator has the ability to use either the device or simulator SDK without |
| needing CMake to be re\-run. The SDK can be selected at build time. |
| But since some architectures can be supported by both the device and the |
| simulator SDKs (e.g. \fBarm64\fP with Xcode 12 or later), not all combinations |
| can be represented in a single universal binary. The only solution in this |
| case is to have multiple object files. |
| .sp |
| \fBIMPORTED_OBJECTS\fP doesn\(aqt support generator expressions, so every file |
| it lists needs to be valid for every architecture and SDK. If incorporating |
| object files that are not universal binaries, the path and/or file name of |
| each object file has to somehow encapsulate the different architectures and |
| SDKs. With the \fBXcode\fP generator, Xcode variables of the form |
| \fB$(...)\fP can be used to represent these aspects and Xcode will substitute |
| the appropriate values at build time. CMake doesn\(aqt interpret these |
| variables and embeds them unchanged in the Xcode project file. |
| \fB$(CURRENT_ARCH)\fP can be used to represent the architecture, while |
| \fB$(EFFECTIVE_PLATFORM_NAME)\fP can be used to differentiate between SDKs. |
| .sp |
| The following shows one example of how these two variables can be used to |
| refer to an object file whose location depends on both the SDK and the |
| architecture: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(someObjs OBJECT IMPORTED) |
| |
| set_property(TARGET someObjs PROPERTY IMPORTED_OBJECTS |
| # Quotes are required because of the () |
| "/path/to/somewhere/objects$(EFFECTIVE_PLATFORM_NAME)/$(CURRENT_ARCH)/func.o" |
| ) |
| |
| # Example paths: |
| # /path/to/somewhere/objects\-iphoneos/arm64/func.o |
| # /path/to/somewhere/objects\-iphonesimulator/x86_64/func.o |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In some cases, you may want to have configuration\-specific object files |
| as well. The \fB$(CONFIGURATION)\fP Xcode variable is often used for this and |
| can be used in conjunction with the others mentioned above: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(someObjs OBJECT IMPORTED) |
| set_property(TARGET someObjs PROPERTY IMPORTED_OBJECTS |
| "/path/to/somewhere/$(CONFIGURATION)$(EFFECTIVE_PLATFORM_NAME)/$(CURRENT_ARCH)/func.o" |
| ) |
| |
| # Example paths: |
| # /path/to/somewhere/Release\-iphoneos/arm64/func.o |
| # /path/to/somewhere/Debug\-iphonesimulator/x86_64/func.o |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| When any Xcode variable is used, CMake is not able to fully evaluate the |
| path(s) at configure time. One consequence of this is that the |
| configuration\-specific \fBIMPORTED_OBJECTS_<CONFIG>\fP properties cannot |
| be used, since CMake cannot determine whether an object file exists at a |
| particular \fB<CONFIG>\fP location. The \fBIMPORTED_OBJECTS\fP property must be |
| used for these situations and the configuration\-specific aspects of the path |
| should be handled by the \fB$(CONFIGURATION)\fP Xcode variable. |
| .SS IMPORTED_OBJECTS_<CONFIG> |
| .sp |
| New in version 3.9. |
| |
| .sp |
| \fB<CONFIG>\fP\-specific version of \fBIMPORTED_OBJECTS\fP property. |
| .sp |
| Configuration names correspond to those provided by the project from |
| which the target is imported. |
| .SS Xcode Generator Considerations |
| .sp |
| Do not use this \fB<CONFIG>\fP\-specific property if you need to use Xcode |
| variables like \fB$(CURRENT_ARCH)\fP or \fB$(EFFECTIVE_PLATFORM_NAME)\fP in |
| the value. The \fB<CONFIG>\fP\-specific properties will be ignored in such |
| cases because CMake cannot determine whether a file exists at the |
| configuration\-specific path at configuration time. For such cases, use |
| \fBIMPORTED_OBJECTS\fP instead. |
| .SS IMPORTED_SONAME |
| .sp |
| The \fBsoname\fP of an \fBIMPORTED\fP target of shared library type. |
| .sp |
| Set this to the \fBsoname\fP embedded in an imported shared library. This |
| is meaningful only on platforms supporting the feature. Ignored for |
| non\-imported targets. |
| .SS IMPORTED_SONAME_<CONFIG> |
| .sp |
| <CONFIG>\-specific version of \fBIMPORTED_SONAME\fP property. |
| .sp |
| Configuration names correspond to those provided by the project from |
| which the target is imported. |
| .SS IMPORT_PREFIX |
| .sp |
| What comes before the import library name. |
| .sp |
| Similar to the target property \fBPREFIX\fP, but used for import libraries |
| (typically corresponding to a \fBDLL\fP) instead of regular libraries. A |
| target property that can be set to override the prefix (such as \fBlib\fP) |
| on an import library name. |
| .SS IMPORT_SUFFIX |
| .sp |
| What comes after the import library name. |
| .sp |
| Similar to the target property \fBSUFFIX\fP, but used |
| for import libraries (typically corresponding to a \fBDLL\fP) instead of |
| regular libraries. A target property that can be set to override |
| the suffix (such as \fB\&.lib\fP) on an import library name. |
| .SS INCLUDE_DIRECTORIES |
| .sp |
| List of preprocessor include file search directories. |
| .sp |
| This property specifies the list of directories given so far to the |
| \fBtarget_include_directories()\fP command. In addition to accepting |
| values from that command, values may be set directly on any |
| target using the \fBset_property()\fP command. A target gets its |
| initial value for this property from the value of the |
| \fBINCLUDE_DIRECTORIES\fP directory property. Both directory and |
| target property values are adjusted by calls to the |
| \fBinclude_directories()\fP command. |
| .sp |
| The value of this property is used by the generators to set the include |
| paths for the compiler. |
| .sp |
| Relative paths should not be added to this property directly. Use one of |
| the commands above instead to handle relative paths. |
| .sp |
| Contents of \fBINCLUDE_DIRECTORIES\fP may use \fBcmake\-generator\-expressions(7)\fP with |
| the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .SS INSTALL_NAME_DIR |
| .sp |
| Directory name for installed targets on Apple platforms. |
| .sp |
| \fBINSTALL_NAME_DIR\fP is a string specifying the directory portion of the |
| "install_name" field of shared libraries on Apple platforms for |
| installed targets. When not set, the default directory used is determined |
| by \fBMACOSX_RPATH\fP\&. Policies \fBCMP0068\fP and \fBCMP0042\fP |
| are also relevant. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_INSTALL_NAME_DIR\fP if it is set when a target is |
| created. |
| .sp |
| This property supports \fBgenerator expressions\fP\&. |
| In particular, the \fB$<INSTALL_PREFIX>\fP generator expression can be |
| used to set the directory relative to the install\-time prefix. |
| .SS INSTALL_REMOVE_ENVIRONMENT_RPATH |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Controls whether toolchain\-defined rpaths should be removed during installation. |
| .sp |
| When a target is being installed, CMake may need to rewrite its rpath |
| information. This occurs when the install rpath (as specified by the |
| \fBINSTALL_RPATH\fP target property) has different contents to the rpath |
| that the target was built with. Some toolchains insert their own rpath |
| contents into the binary as part of the build. By default, CMake will |
| preserve those extra inserted contents in the install rpath. For those |
| scenarios where such toolchain\-inserted entries need to be discarded during |
| install, set the \fBINSTALL_REMOVE_ENVIRONMENT_RPATH\fP target property to true. |
| .sp |
| This property is initialized by the value of |
| \fBCMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH\fP when the target is created. |
| .SS INSTALL_RPATH |
| .sp |
| The rpath to use for installed targets. |
| .sp |
| A semicolon\-separated list specifying the rpath to use in installed |
| targets (for platforms that support it). This property is initialized |
| by the value of the variable \fBCMAKE_INSTALL_RPATH\fP if it is set when |
| a target is created. |
| .sp |
| Because the rpath may contain \fB${ORIGIN}\fP, which coincides with CMake syntax, |
| the contents of \fBINSTALL_RPATH\fP are properly escaped in the |
| \fBcmake_install.cmake\fP script (see policy \fBCMP0095\fP\&.) |
| .sp |
| This property supports |
| \fBgenerator expressions\fP\&. |
| .SS INSTALL_RPATH_USE_LINK_PATH |
| .sp |
| Add paths to linker search and installed rpath. |
| .sp |
| \fBINSTALL_RPATH_USE_LINK_PATH\fP is a boolean that if set to \fBTrue\fP |
| will append to the runtime search path (rpath) of installed binaries |
| any directories outside the project that are in the linker search path or |
| contain linked library files. The directories are appended after the |
| value of the \fBINSTALL_RPATH\fP target property. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_INSTALL_RPATH_USE_LINK_PATH\fP if it is set when a target is |
| created. |
| .SS INTERFACE_AUTOUIC_OPTIONS |
| .sp |
| List of interface options to pass to uic. |
| .sp |
| Targets may populate this property to publish the options |
| required to use when invoking \fBuic\fP\&. Consuming targets can add entries to their |
| own \fBAUTOUIC_OPTIONS\fP property such as |
| \fB$<TARGET_PROPERTY:foo,INTERFACE_AUTOUIC_OPTIONS>\fP to use the uic options |
| specified in the interface of \fBfoo\fP\&. This is done automatically by |
| the \fBtarget_link_libraries()\fP command. |
| .sp |
| This property supports generator expressions. See the |
| \fBcmake\-generator\-expressions(7)\fP manual for available expressions. |
| .SS INTERFACE_COMPILE_DEFINITIONS |
| .sp |
| List of public compile definitions requirements for a library. |
| .sp |
| Targets may populate this property to publish the compile definitions |
| required to compile against the headers for the target. The \fBtarget_compile_definitions()\fP |
| command populates this property with values given to the \fBPUBLIC\fP and |
| \fBINTERFACE\fP keywords. Projects may also get and set the property directly. |
| .sp |
| When target dependencies are specified using \fBtarget_link_libraries()\fP, |
| CMake will read this property from all target dependencies to determine the |
| build properties of the consumer. |
| .sp |
| Contents of \fBINTERFACE_COMPILE_DEFINITIONS\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| \-manual for more on defining buildsystem properties. |
| .SS INTERFACE_COMPILE_FEATURES |
| .sp |
| New in version 3.1. |
| |
| .sp |
| List of public compile features requirements for a library. |
| .sp |
| Targets may populate this property to publish the compile features |
| required to compile against the headers for the target. The \fBtarget_compile_features()\fP |
| command populates this property with values given to the \fBPUBLIC\fP and |
| \fBINTERFACE\fP keywords. Projects may also get and set the property directly. |
| .sp |
| When target dependencies are specified using \fBtarget_link_libraries()\fP, |
| CMake will read this property from all target dependencies to determine the |
| build properties of the consumer. |
| .sp |
| Contents of \fBINTERFACE_COMPILE_FEATURES\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| \-manual for more on defining buildsystem properties. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on compile |
| features and a list of supported compilers. |
| .SS INTERFACE_COMPILE_OPTIONS |
| .sp |
| List of public compile options requirements for a library. |
| .sp |
| Targets may populate this property to publish the compile options |
| required to compile against the headers for the target. The \fBtarget_compile_options()\fP |
| command populates this property with values given to the \fBPUBLIC\fP and |
| \fBINTERFACE\fP keywords. Projects may also get and set the property directly. |
| .sp |
| When target dependencies are specified using \fBtarget_link_libraries()\fP, |
| CMake will read this property from all target dependencies to determine the |
| build properties of the consumer. |
| .sp |
| Contents of \fBINTERFACE_COMPILE_OPTIONS\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| \-manual for more on defining buildsystem properties. |
| .SS INTERFACE_HEADER_SETS |
| .sp |
| New in version 3.23. |
| |
| .sp |
| Read\-only list of the target\(aqs \fBINTERFACE\fP and \fBPUBLIC\fP header sets (i.e. |
| all file sets with the type \fBHEADERS\fP). Files listed in these header sets |
| can be installed with \fBinstall(TARGETS)\fP and exported with |
| \fBinstall(EXPORT)\fP and \fBexport()\fP\&. |
| .sp |
| Header sets may be defined using the \fBtarget_sources()\fP command |
| \fBFILE_SET\fP option with type \fBHEADERS\fP\&. |
| .sp |
| See also \fBHEADER_SETS\fP\&. |
| .SS INTERFACE_INCLUDE_DIRECTORIES |
| .sp |
| List of public include directories requirements for a library. |
| .sp |
| Targets may populate this property to publish the include directories |
| required to compile against the headers for the target. The \fBtarget_include_directories()\fP |
| command populates this property with values given to the \fBPUBLIC\fP and |
| \fBINTERFACE\fP keywords. Projects may also get and set the property directly. |
| .sp |
| When target dependencies are specified using \fBtarget_link_libraries()\fP, |
| CMake will read this property from all target dependencies to determine the |
| build properties of the consumer. |
| .sp |
| Contents of \fBINTERFACE_INCLUDE_DIRECTORIES\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| \-manual for more on defining buildsystem properties. |
| .sp |
| Include directories usage requirements commonly differ between the build\-tree |
| and the install\-tree. The \fBBUILD_INTERFACE\fP and \fBINSTALL_INTERFACE\fP |
| generator expressions can be used to describe separate usage requirements |
| based on the usage location. Relative paths are allowed within the |
| \fBINSTALL_INTERFACE\fP expression and are interpreted relative to the |
| installation prefix. For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_include_directories(mylib INTERFACE |
| $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib> |
| $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Creating Relocatable Packages |
| .sp |
| Note that it is not advisable to populate the \fBINSTALL_INTERFACE\fP of |
| the \fBINTERFACE_INCLUDE_DIRECTORIES\fP of a target with absolute paths to the include |
| directories of dependencies. That would hard\-code into installed packages |
| the include directory paths for dependencies |
| \fBas found on the machine the package was made on\fP\&. |
| .sp |
| The \fBINSTALL_INTERFACE\fP of the \fBINTERFACE_INCLUDE_DIRECTORIES\fP is only |
| suitable for specifying the required include directories for headers |
| provided with the target itself, not those provided by the transitive |
| dependencies listed in its \fBINTERFACE_LINK_LIBRARIES\fP target |
| property. Those dependencies should themselves be targets that specify |
| their own header locations in \fBINTERFACE_INCLUDE_DIRECTORIES\fP\&. |
| .sp |
| See the Creating Relocatable Packages section of the |
| \fBcmake\-packages(7)\fP manual for discussion of additional care |
| that must be taken when specifying usage requirements while creating |
| packages for redistribution. |
| .SS INTERFACE_LINK_DEPENDS |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Additional public interface files on which a target binary depends for linking. |
| .sp |
| This property is supported only by \fBNinja\fP and |
| Makefile Generators\&. |
| It is intended to specify dependencies on "linker scripts" for |
| custom Makefile link rules. |
| .sp |
| When target dependencies are specified using \fBtarget_link_libraries()\fP, |
| CMake will read this property from all target dependencies to determine the |
| build properties of the consumer. |
| .sp |
| Contents of \fBINTERFACE_LINK_DEPENDS\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| \-manual for more on defining buildsystem properties. |
| .sp |
| Link dependency files usage requirements commonly differ between the build\-tree |
| and the install\-tree. The \fBBUILD_INTERFACE\fP and \fBINSTALL_INTERFACE\fP |
| generator expressions can be used to describe separate usage requirements |
| based on the usage location. Relative paths are allowed within the |
| \fBINSTALL_INTERFACE\fP expression and are interpreted relative to the |
| installation prefix. For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET mylib PROPERTY INTERFACE_LINK_DEPENDS |
| $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/mylinkscript> |
| $<INSTALL_INTERFACE:mylinkscript> # <prefix>/mylinkscript |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS INTERFACE_LINK_DIRECTORIES |
| .sp |
| New in version 3.13. |
| |
| .sp |
| List of public link directories requirements for a library. |
| .sp |
| Targets may populate this property to publish the link directories |
| required to compile against the headers for the target. The \fBtarget_link_directories()\fP |
| command populates this property with values given to the \fBPUBLIC\fP and |
| \fBINTERFACE\fP keywords. Projects may also get and set the property directly. |
| .sp |
| When target dependencies are specified using \fBtarget_link_libraries()\fP, |
| CMake will read this property from all target dependencies to determine the |
| build properties of the consumer. |
| .sp |
| Contents of \fBINTERFACE_LINK_DIRECTORIES\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| \-manual for more on defining buildsystem properties. |
| .SS INTERFACE_LINK_LIBRARIES |
| .sp |
| List public interface libraries for a library. |
| .sp |
| This property contains the list of transitive link dependencies. When |
| the target is linked into another target using the |
| \fBtarget_link_libraries()\fP command, the libraries listed (and |
| recursively their link interface libraries) will be provided to the |
| other target also. This property is overridden by the |
| \fBLINK_INTERFACE_LIBRARIES\fP or |
| \fBLINK_INTERFACE_LIBRARIES_<CONFIG>\fP property if policy |
| \fBCMP0022\fP is \fBOLD\fP or unset. |
| .sp |
| The value of this property is used by the generators when constructing |
| the link rule for a dependent target. A dependent target\(aqs direct |
| link dependencies, specified by its \fBLINK_LIBRARIES\fP target |
| property, are linked first, followed by indirect dependencies from the |
| transitive closure of the direct dependencies\(aq |
| \fBINTERFACE_LINK_LIBRARIES\fP properties. See policy \fBCMP0022\fP\&. |
| .sp |
| Contents of \fBINTERFACE_LINK_LIBRARIES\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| A call to \fBtarget_link_libraries(<target> ...)\fP may update this |
| property on \fB<target>\fP\&. If \fB<target>\fP was not created in the same |
| directory as the call then \fBtarget_link_libraries()\fP will wrap each |
| entry with the form \fB::@(directory\-id);...;::@\fP, where the \fB::@\fP is |
| literal and the \fB(directory\-id)\fP is unspecified. |
| This tells the generators that the named libraries must be looked up in |
| the scope of the caller rather than in the scope in which the |
| \fB<target>\fP was created. Valid directory ids are stripped on export |
| by the \fBinstall(EXPORT)\fP and \fBexport()\fP commands. |
| .UNINDENT |
| .UNINDENT |
| .SS Creating Relocatable Packages |
| .sp |
| Note that it is not advisable to populate the |
| \fBINTERFACE_LINK_LIBRARIES\fP of a target with absolute paths to dependencies. |
| That would hard\-code into installed packages the library file paths |
| for dependencies \fBas found on the machine the package was made on\fP\&. |
| .sp |
| See the Creating Relocatable Packages section of the |
| \fBcmake\-packages(7)\fP manual for discussion of additional care |
| that must be taken when specifying usage requirements while creating |
| packages for redistribution. |
| .SS INTERFACE_LINK_OPTIONS |
| .sp |
| New in version 3.13. |
| |
| .sp |
| List of public link options requirements for a library. |
| .sp |
| Targets may populate this property to publish the link options |
| required to compile against the headers for the target. The \fBtarget_link_options()\fP |
| command populates this property with values given to the \fBPUBLIC\fP and |
| \fBINTERFACE\fP keywords. Projects may also get and set the property directly. |
| .sp |
| When target dependencies are specified using \fBtarget_link_libraries()\fP, |
| CMake will read this property from all target dependencies to determine the |
| build properties of the consumer. |
| .sp |
| Contents of \fBINTERFACE_LINK_OPTIONS\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| \-manual for more on defining buildsystem properties. |
| .SS INTERFACE_POSITION_INDEPENDENT_CODE |
| .sp |
| Whether consumers need to create a position\-independent target |
| .sp |
| The \fBINTERFACE_POSITION_INDEPENDENT_CODE\fP property informs consumers of |
| this target whether they must set their |
| \fBPOSITION_INDEPENDENT_CODE\fP property to \fBON\fP\&. If this |
| property is set to \fBON\fP, then the \fBPOSITION_INDEPENDENT_CODE\fP |
| property on all consumers will be set to \fBON\fP\&. Similarly, if this |
| property is set to \fBOFF\fP, then the \fBPOSITION_INDEPENDENT_CODE\fP |
| property on all consumers will be set to \fBOFF\fP\&. If this property is |
| undefined, then consumers will determine their |
| \fBPOSITION_INDEPENDENT_CODE\fP property by other means. Consumers |
| must ensure that the targets that they link to have a consistent |
| requirement for their \fBINTERFACE_POSITION_INDEPENDENT_CODE\fP property. |
| .sp |
| Contents of \fBINTERFACE_POSITION_INDEPENDENT_CODE\fP may use |
| "generator expressions" with the syntax \fB$<...>\fP\&. See the |
| \fBcmake\-generator\-expressions(7)\fP manual for available expressions. |
| See the \fBcmake\-buildsystem(7)\fP manual for more on defining buildsystem |
| properties. |
| .SS INTERFACE_PRECOMPILE_HEADERS |
| .sp |
| New in version 3.16. |
| |
| .sp |
| List of interface header files to precompile into consuming targets. |
| .sp |
| Targets may populate this property to publish the header files |
| for consuming targets to precompile. The \fBtarget_precompile_headers()\fP |
| command populates this property with values given to the \fBPUBLIC\fP and |
| \fBINTERFACE\fP keywords. Projects may also get and set the property directly. |
| See the discussion in \fBtarget_precompile_headers()\fP for guidance on |
| appropriate use of this property for installed or exported targets. |
| .sp |
| Contents of \fBINTERFACE_PRECOMPILE_HEADERS\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .SS INTERFACE_SOURCES |
| .sp |
| New in version 3.1. |
| |
| .sp |
| List of interface sources to compile into consuming targets. |
| .sp |
| Targets may populate this property to publish the sources |
| for consuming targets to compile. The \fBtarget_sources()\fP command |
| populates this property with values given to the \fBPUBLIC\fP and |
| \fBINTERFACE\fP keywords. Projects may also get and set the property directly. |
| .sp |
| When target dependencies are specified using \fBtarget_link_libraries()\fP, |
| CMake will read this property from all target dependencies to determine the |
| sources of the consumer. |
| .sp |
| Contents of \fBINTERFACE_SOURCES\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .SS INTERFACE_SYSTEM_INCLUDE_DIRECTORIES |
| .sp |
| List of public system include directories for a library. |
| .sp |
| Targets may populate this property to publish the include directories |
| which contain system headers, and therefore should not result in |
| compiler warnings. Additionally, system include directories are searched |
| after normal include directories regardless of the order specified. |
| .sp |
| The \fBtarget_include_directories(SYSTEM)\fP command signature |
| populates this property with values given to the \fBPUBLIC\fP and |
| \fBINTERFACE\fP keywords. |
| .sp |
| Projects may also get and set the property directly, but must be aware that |
| adding directories to this property does not make those directories used |
| during compilation. Adding directories to this property marks directories |
| as \fBSYSTEM\fP which otherwise would be used in a non\-\fBSYSTEM\fP manner. This |
| can appear similar to \(aqduplication\(aq, so prefer the |
| high\-level \fBtarget_include_directories(SYSTEM)\fP command and avoid |
| setting the property by low\-level means. |
| .sp |
| When target dependencies are specified using \fBtarget_link_libraries()\fP, |
| CMake will read this property from all target dependencies to mark the |
| same include directories as containing system headers. |
| .sp |
| Contents of \fBINTERFACE_SYSTEM_INCLUDE_DIRECTORIES\fP may use "generator |
| expressions" with the syntax \fB$<...>\fP\&. See the |
| \fBcmake\-generator\-expressions(7)\fP manual for available expressions. |
| See the \fBcmake\-buildsystem(7)\fP manual for more on defining |
| buildsystem properties. |
| .SS INTERPROCEDURAL_OPTIMIZATION |
| .sp |
| Enable interprocedural optimization for a target. |
| .sp |
| If set to true, enables interprocedural optimizations if they are |
| known \fBto be supported\fP by the compiler. Depending |
| on value of policy \fBCMP0069\fP, the error will be reported or ignored, |
| if interprocedural optimization is enabled but not supported. |
| .sp |
| This property is initialized by the |
| \fBCMAKE_INTERPROCEDURAL_OPTIMIZATION\fP variable if it is set when a |
| target is created. |
| .SS INTERPROCEDURAL_OPTIMIZATION_<CONFIG> |
| .sp |
| Per\-configuration interprocedural optimization for a target. |
| .sp |
| This is a per\-configuration version of \fBINTERPROCEDURAL_OPTIMIZATION\fP\&. |
| If set, this property overrides the generic property for the named |
| configuration. |
| .sp |
| This property is initialized by the |
| \fBCMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG>\fP variable if it is set |
| when a target is created. |
| .SS IOS_INSTALL_COMBINED |
| .sp |
| New in version 3.5. |
| |
| .sp |
| Build a combined (device and simulator) target when installing. |
| .sp |
| When this property is set to set to false (which is the default) then it will |
| either be built with the device SDK or the simulator SDK depending on the SDK |
| set. But if this property is set to true then the target will at install time |
| also be built for the corresponding SDK and combined into one library. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| If a selected architecture is available for both: device SDK and simulator |
| SDK it will be built for the SDK selected by \fBCMAKE_OSX_SYSROOT\fP |
| and removed from the corresponding SDK. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This feature requires at least Xcode version 6. |
| .SS ISPC_HEADER_DIRECTORY |
| .sp |
| New in version 3.19. |
| |
| .sp |
| Specify relative output directory for ISPC headers provided by the target. |
| .sp |
| If the target contains ISPC source files, this specifies the directory in which |
| the generated headers will be placed. Relative paths are treated with respect to |
| the value of \fBCMAKE_CURRENT_BINARY_DIR\fP\&. When this property is not set, the |
| headers will be placed a generator defined build directory. If the variable |
| \fBCMAKE_ISPC_HEADER_DIRECTORY\fP is set when a target is created |
| its value is used to initialize this property. |
| .SS ISPC_HEADER_SUFFIX |
| .sp |
| New in version 3.19.2. |
| |
| .sp |
| Specify output suffix to be used for ISPC generated headers provided by the target. |
| .sp |
| This property is initialized by the value of the \fBCMAKE_ISPC_HEADER_SUFFIX\fP |
| variable if it is set when a target is created. |
| .sp |
| If the target contains ISPC source files, this specifies the header suffix to |
| be used for the generated headers. |
| .sp |
| The default value is \fB_ispc.h\fP\&. |
| .SS ISPC_INSTRUCTION_SETS |
| .sp |
| New in version 3.19. |
| |
| .sp |
| List of instruction set architectures to generate code for. |
| .sp |
| This property is initialized by the value of the \fBCMAKE_ISPC_INSTRUCTION_SETS\fP |
| variable if it is set when a target is created. |
| .sp |
| The \fBISPC_INSTRUCTION_SETS\fP target property must be used when generating for multiple |
| instruction sets so that CMake can track what object files will be generated. |
| .SS Examples |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET tgt PROPERTY ISPC_INSTRUCTION_SETS avx2\-i32x4 avx512skx\-i32x835) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Generates code for avx2 and avx512skx target architectures. |
| .SS JOB_POOL_COMPILE |
| .sp |
| Ninja only: Pool used for compiling. |
| .sp |
| The number of parallel compile processes could be limited by defining |
| pools with the global \fBJOB_POOLS\fP |
| property and then specifying here the pool name. |
| .sp |
| For instance: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET myexe PROPERTY JOB_POOL_COMPILE ten_jobs) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This property is initialized by the value of |
| \fBCMAKE_JOB_POOL_COMPILE\fP\&. |
| .SS JOB_POOL_LINK |
| .sp |
| Ninja only: Pool used for linking. |
| .sp |
| The number of parallel link processes could be limited by defining |
| pools with the global \fBJOB_POOLS\fP |
| property and then specifying here the pool name. |
| .sp |
| For instance: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET myexe PROPERTY JOB_POOL_LINK two_jobs) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This property is initialized by the value of \fBCMAKE_JOB_POOL_LINK\fP\&. |
| .SS JOB_POOL_PRECOMPILE_HEADER |
| .sp |
| New in version 3.17. |
| |
| .sp |
| Ninja only: Pool used for generating pre\-compiled headers. |
| .sp |
| The number of parallel compile processes could be limited by defining |
| pools with the global \fBJOB_POOLS\fP |
| property and then specifying here the pool name. |
| .sp |
| For instance: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET myexe PROPERTY JOB_POOL_PRECOMPILE_HEADER two_jobs) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This property is initialized by the value of |
| \fBCMAKE_JOB_POOL_PRECOMPILE_HEADER\fP\&. |
| .sp |
| If neither \fI\%JOB_POOL_PRECOMPILE_HEADER\fP nor |
| \fBCMAKE_JOB_POOL_PRECOMPILE_HEADER\fP are set then |
| \fBJOB_POOL_COMPILE\fP will be used for this task. |
| .SS LABELS |
| .sp |
| Specify a list of text labels associated with a target. |
| .sp |
| Target label semantics are currently unspecified. |
| .SS <LANG>_CLANG_TIDY |
| .sp |
| New in version 3.6. |
| |
| .sp |
| This property is implemented only when \fB<LANG>\fP is \fBC\fP, \fBCXX\fP, \fBOBJC\fP or \fBOBJCXX\fP\&. |
| .sp |
| Specify a semicolon\-separated list containing a command |
| line for the \fBclang\-tidy\fP tool. The Makefile Generators |
| and the \fBNinja\fP generator will run this tool along with the |
| compiler and report a warning if the tool reports any problems. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_<LANG>_CLANG_TIDY\fP variable if it is set |
| when a target is created. |
| .SS <LANG>_COMPILER_LAUNCHER |
| .sp |
| New in version 3.4. |
| |
| .sp |
| This property is implemented only when \fB<LANG>\fP is \fBC\fP, \fBCXX\fP, |
| \fBFortran\fP, \fBHIP\fP, \fBISPC\fP, \fBOBJC\fP, \fBOBJCXX\fP, or \fBCUDA\fP\&. |
| .sp |
| Specify a semicolon\-separated list containing a command line |
| for a compiler launching tool. The Makefile Generators and the |
| \fBNinja\fP generator will run this tool and pass the compiler and |
| its arguments to the tool. Some example tools are distcc and ccache. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_<LANG>_COMPILER_LAUNCHER\fP variable if it is set |
| when a target is created. |
| .SS <LANG>_CPPCHECK |
| .sp |
| New in version 3.10. |
| |
| .sp |
| This property is supported only when \fB<LANG>\fP is \fBC\fP or \fBCXX\fP\&. |
| .sp |
| Specify a semicolon\-separated list containing a command line |
| for the \fBcppcheck\fP static analysis tool. The Makefile Generators |
| and the \fBNinja\fP generator will run \fBcppcheck\fP along with the |
| compiler and report any problems. If the command\-line specifies the |
| exit code options to \fBcppcheck\fP then the build will fail if the |
| tool returns non\-zero. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_<LANG>_CPPCHECK\fP variable if it is set when a target is |
| created. |
| .SS <LANG>_CPPLINT |
| .sp |
| New in version 3.8. |
| |
| .sp |
| This property is supported only when \fB<LANG>\fP is \fBC\fP or \fBCXX\fP\&. |
| .sp |
| Specify a semicolon\-separated list containing a command line |
| for the \fBcpplint\fP style checker. The Makefile Generators and the |
| \fBNinja\fP generator will run \fBcpplint\fP along with the compiler |
| and report any problems. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_<LANG>_CPPLINT\fP variable if it is set when a target is |
| created. |
| .SS <LANG>_EXTENSIONS |
| .sp |
| The variations are: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBC_EXTENSIONS\fP |
| .IP \(bu 2 |
| \fBCXX_EXTENSIONS\fP |
| .IP \(bu 2 |
| \fBCUDA_EXTENSIONS\fP |
| .IP \(bu 2 |
| \fBHIP_EXTENSIONS\fP |
| .IP \(bu 2 |
| \fBOBJC_EXTENSIONS\fP |
| .IP \(bu 2 |
| \fBOBJCXX_EXTENSIONS\fP |
| .UNINDENT |
| .sp |
| These properties specify whether compiler\-specific extensions are requested. |
| .sp |
| These properties are initialized by the value of the |
| \fBCMAKE_<LANG>_EXTENSIONS\fP variable if it is set when a target is |
| created and otherwise by the value of |
| \fBCMAKE_<LANG>_EXTENSIONS_DEFAULT\fP (see \fBCMP0128\fP). |
| .sp |
| For supported CMake versions see the respective pages. |
| To control language standard versions see \fB<LANG>_STANDARD\fP\&. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .SS <LANG>_INCLUDE_WHAT_YOU_USE |
| .sp |
| New in version 3.3. |
| |
| .sp |
| This property is implemented only when \fB<LANG>\fP is \fBC\fP or \fBCXX\fP\&. |
| .sp |
| Specify a semicolon\-separated list containing a command |
| line for the \fBinclude\-what\-you\-use\fP tool. The Makefile Generators |
| and the \fBNinja\fP generator will run this tool along with the |
| compiler and report a warning if the tool reports any problems. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_<LANG>_INCLUDE_WHAT_YOU_USE\fP variable if it is set |
| when a target is created. |
| .SS <LANG>_LINKER_LAUNCHER |
| .sp |
| New in version 3.21. |
| |
| .sp |
| This property is implemented only when \fB<LANG>\fP is \fBC\fP, \fBCXX\fP, |
| \fBOBJC\fP, or \fBOBJCXX\fP |
| .sp |
| Specify a semicolon\-separated list containing a |
| command line for a linker launching tool. The Makefile Generators and the |
| \fBNinja\fP generator will run this tool and pass the linker and its |
| arguments to the tool. This is useful for tools such as static analyzers. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_<LANG>_LINKER_LAUNCHER\fP variable if it is set when a target is |
| created. |
| .SS <LANG>_STANDARD |
| .sp |
| The variations are: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBC_STANDARD\fP |
| .IP \(bu 2 |
| \fBCXX_STANDARD\fP |
| .IP \(bu 2 |
| \fBCUDA_STANDARD\fP |
| .IP \(bu 2 |
| \fBHIP_STANDARD\fP |
| .IP \(bu 2 |
| \fBOBJC_STANDARD\fP |
| .IP \(bu 2 |
| \fBOBJCXX_STANDARD\fP |
| .UNINDENT |
| .sp |
| These properties specify language standard versions which are requested. When a |
| newer standard is specified than is supported by the compiler, then it will |
| fallback to the latest supported standard. This "decay" behavior may be |
| controlled with the \fB<LANG>_STANDARD_REQUIRED\fP target property. |
| .sp |
| Note that the actual language standard used may be higher than that specified |
| by \fB<LANG>_STANDARD\fP, regardless of the value of |
| \fB<LANG>_STANDARD_REQUIRED\fP\&. In particular, |
| transitive usage requirements or the use of |
| \fBcompile features\fP can raise the required |
| language standard above what \fB<LANG>_STANDARD\fP specifies. |
| .sp |
| These properties are initialized by the value of the |
| \fBCMAKE_<LANG>_STANDARD\fP variable if it is set when a target is |
| created. |
| .sp |
| For supported values and CMake versions see the respective pages. |
| To control compiler\-specific extensions see \fB<LANG>_EXTENSIONS\fP\&. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .SS <LANG>_STANDARD_REQUIRED |
| .sp |
| The variations are: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBC_STANDARD_REQUIRED\fP |
| .IP \(bu 2 |
| \fBCXX_STANDARD_REQUIRED\fP |
| .IP \(bu 2 |
| \fBCUDA_STANDARD_REQUIRED\fP |
| .IP \(bu 2 |
| \fBHIP_STANDARD_REQUIRED\fP |
| .IP \(bu 2 |
| \fBOBJC_STANDARD_REQUIRED\fP |
| .IP \(bu 2 |
| \fBOBJCXX_STANDARD_REQUIRED\fP |
| .UNINDENT |
| .sp |
| These properties specify whether the value of \fB<LANG>_STANDARD\fP is a |
| requirement. When false or unset, the \fB<LANG>_STANDARD\fP target |
| property is treated as optional and may "decay" to a previous standard if the |
| requested standard is not available. When \fB<LANG>_STANDARD_REQUIRED\fP is set |
| to true, \fB<LANG>_STANDARD\fP becomes a hard requirement and a fatal |
| error will be issued if that requirement cannot be met. |
| .sp |
| Note that the actual language standard used may be higher than that specified |
| by \fB<LANG>_STANDARD\fP, regardless of the value of |
| \fB<LANG>_STANDARD_REQUIRED\fP\&. In particular, |
| transitive usage requirements or the use of |
| \fBcompile features\fP can raise the required |
| language standard above what \fB<LANG>_STANDARD\fP specifies. |
| .sp |
| These properties are initialized by the value of the |
| \fBCMAKE_<LANG>_STANDARD_REQUIRED\fP variable if it is set when a target |
| is created. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .SS <LANG>_VISIBILITY_PRESET |
| .sp |
| Value for symbol visibility compile flags |
| .sp |
| The \fB<LANG>_VISIBILITY_PRESET\fP property determines the value passed in a |
| visibility related compile option, such as \fB\-fvisibility=\fP for \fB<LANG>\fP\&. |
| This property affects compilation in sources of all types of targets |
| (subject to policy \fBCMP0063\fP). |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_<LANG>_VISIBILITY_PRESET\fP variable if it is set when a |
| target is created. |
| .SS LIBRARY_OUTPUT_DIRECTORY |
| .sp |
| Output directory in which to build LIBRARY target files. |
| .sp |
| This property specifies the directory into which library target files |
| should be built. The property value may use |
| \fBgenerator expressions\fP\&. |
| Multi\-configuration generators (Visual Studio, |
| \fBXcode\fP, \fBNinja Multi\-Config\fP) append a |
| per\-configuration subdirectory to the specified directory unless a generator |
| expression is used. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_LIBRARY_OUTPUT_DIRECTORY\fP variable if it is set when a target is created. |
| .sp |
| See also the \fBLIBRARY_OUTPUT_DIRECTORY_<CONFIG>\fP target property. |
| .SS LIBRARY_OUTPUT_DIRECTORY_<CONFIG> |
| .sp |
| Per\-configuration output directory for |
| LIBRARY target files. |
| .sp |
| This is a per\-configuration version of the |
| \fBLIBRARY_OUTPUT_DIRECTORY\fP target property, but |
| multi\-configuration generators (Visual Studio Generators, |
| \fBXcode\fP) do NOT append a |
| per\-configuration subdirectory to the specified directory. This |
| property is initialized by the value of the |
| \fBCMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG>\fP variable if |
| it is set when a target is created. |
| .sp |
| Contents of \fBLIBRARY_OUTPUT_DIRECTORY_<CONFIG>\fP may use |
| \fBgenerator expressions\fP\&. |
| .SS LIBRARY_OUTPUT_NAME |
| .sp |
| Output name for LIBRARY target files. |
| .sp |
| This property specifies the base name for library target files. It |
| overrides \fBOUTPUT_NAME\fP and \fBOUTPUT_NAME_<CONFIG>\fP |
| properties. |
| .sp |
| See also the \fBLIBRARY_OUTPUT_NAME_<CONFIG>\fP target property. |
| .SS LIBRARY_OUTPUT_NAME_<CONFIG> |
| .sp |
| Per\-configuration output name for |
| LIBRARY target files. |
| .sp |
| This is the configuration\-specific version of the |
| \fBLIBRARY_OUTPUT_NAME\fP target property. |
| .SS LINK_DEPENDS |
| .sp |
| Additional files on which a target binary depends for linking. |
| .sp |
| Specifies a semicolon\-separated list of full\-paths to files on which |
| the link rule for this target depends. The target binary will be |
| linked if any of the named files is newer than it. |
| .sp |
| This property is supported only by \fBNinja\fP and |
| Makefile Generators\&. It is |
| intended to specify dependencies on "linker scripts" for custom Makefile link |
| rules. |
| .sp |
| Contents of \fBLINK_DEPENDS\fP may use "generator expressions" with |
| the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .SS LINK_DEPENDS_NO_SHARED |
| .sp |
| Do not depend on linked shared library files. |
| .sp |
| Set this property to true to tell CMake generators not to add |
| file\-level dependencies on the shared library files linked by this |
| target. Modification to the shared libraries will not be sufficient |
| to re\-link this target. Logical target\-level dependencies will not be |
| affected so the linked shared libraries will still be brought up to |
| date before this target is built. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_LINK_DEPENDS_NO_SHARED\fP variable if it is set when a |
| target is created. |
| .SS LINK_DIRECTORIES |
| .sp |
| New in version 3.13. |
| |
| .sp |
| List of directories to use for the link step of shared library, module |
| and executable targets. |
| .sp |
| This property holds a semicolon\-separated list of directories |
| specified so far for its target. Use the \fBtarget_link_directories()\fP |
| command to append more search directories. |
| .sp |
| This property is initialized by the \fBLINK_DIRECTORIES\fP directory |
| property when a target is created, and is used by the generators to set |
| the search directories for the linker. |
| .sp |
| Contents of \fBLINK_DIRECTORIES\fP may use "generator expressions" with the |
| syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP manual |
| for available expressions. See the \fBcmake\-buildsystem(7)\fP manual |
| for more on defining buildsystem properties. |
| .SS LINK_FLAGS |
| .sp |
| Additional flags to use when linking this target if it is a shared library, |
| module library, or an executable. Static libraries need to use |
| \fBSTATIC_LIBRARY_OPTIONS\fP or \fBSTATIC_LIBRARY_FLAGS\fP |
| properties. |
| .sp |
| The \fBLINK_FLAGS\fP property, managed as a string, can be used to add extra |
| flags to the link step of a target. \fBLINK_FLAGS_<CONFIG>\fP will add |
| to the configuration \fB<CONFIG>\fP, for example, \fBDEBUG\fP, \fBRELEASE\fP, |
| \fBMINSIZEREL\fP, \fBRELWITHDEBINFO\fP, ... |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This property has been superseded by \fBLINK_OPTIONS\fP property. |
| .UNINDENT |
| .UNINDENT |
| .SS LINK_FLAGS_<CONFIG> |
| .sp |
| Per\-configuration linker flags for a \fBSHARED\fP library, \fBMODULE\fP or |
| \fBEXECUTABLE\fP target. |
| .sp |
| This is the configuration\-specific version of \fBLINK_FLAGS\fP\&. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This property has been superseded by \fBLINK_OPTIONS\fP property. |
| .UNINDENT |
| .UNINDENT |
| .SS LINK_INTERFACE_LIBRARIES |
| .sp |
| List public interface libraries for a shared library or executable. |
| .sp |
| By default linking to a shared library target transitively links to |
| targets with which the library itself was linked. For an executable |
| with exports (see the \fBENABLE_EXPORTS\fP target property) no |
| default transitive link dependencies are used. This property replaces the default |
| transitive link dependencies with an explicit list. When the target |
| is linked into another target using the \fBtarget_link_libraries()\fP |
| command, the libraries listed (and recursively |
| their link interface libraries) will be provided to the other target |
| also. If the list is empty then no transitive link dependencies will |
| be incorporated when this target is linked into another target even if |
| the default set is non\-empty. This property is initialized by the |
| value of the \fBCMAKE_LINK_INTERFACE_LIBRARIES\fP variable if it is |
| set when a target is created. This property is ignored for \fBSTATIC\fP |
| libraries. |
| .sp |
| This property is overridden by the \fBINTERFACE_LINK_LIBRARIES\fP |
| property if policy \fBCMP0022\fP is \fBNEW\fP\&. |
| .sp |
| This property is deprecated. Use \fBINTERFACE_LINK_LIBRARIES\fP |
| instead. |
| .SS Creating Relocatable Packages |
| .sp |
| Note that it is not advisable to populate the |
| \fBLINK_INTERFACE_LIBRARIES\fP of a target with absolute paths to dependencies. |
| That would hard\-code into installed packages the library file paths |
| for dependencies \fBas found on the machine the package was made on\fP\&. |
| .sp |
| See the Creating Relocatable Packages section of the |
| \fBcmake\-packages(7)\fP manual for discussion of additional care |
| that must be taken when specifying usage requirements while creating |
| packages for redistribution. |
| .SS LINK_INTERFACE_LIBRARIES_<CONFIG> |
| .sp |
| Per\-configuration list of public interface libraries for a target. |
| .sp |
| This is the configuration\-specific version of |
| \fBLINK_INTERFACE_LIBRARIES\fP\&. If set, this property completely |
| overrides the generic property for the named configuration. |
| .sp |
| This property is overridden by the \fBINTERFACE_LINK_LIBRARIES\fP |
| property if policy \fBCMP0022\fP is \fBNEW\fP\&. |
| .sp |
| This property is deprecated. Use \fBINTERFACE_LINK_LIBRARIES\fP |
| instead. |
| .SS Creating Relocatable Packages |
| .sp |
| Note that it is not advisable to populate the |
| \fBLINK_INTERFACE_LIBRARIES_<CONFIG>\fP of a target with absolute paths to dependencies. |
| That would hard\-code into installed packages the library file paths |
| for dependencies \fBas found on the machine the package was made on\fP\&. |
| .sp |
| See the Creating Relocatable Packages section of the |
| \fBcmake\-packages(7)\fP manual for discussion of additional care |
| that must be taken when specifying usage requirements while creating |
| packages for redistribution. |
| .SS LINK_INTERFACE_MULTIPLICITY |
| .sp |
| Repetition count for \fBSTATIC\fP libraries with cyclic dependencies. |
| .sp |
| When linking to a \fBSTATIC\fP library target with cyclic dependencies the |
| linker may need to scan more than once through the archives in the |
| strongly connected component of the dependency graph. CMake by |
| default constructs the link line so that the linker will scan through |
| the component at least twice. This property specifies the minimum |
| number of scans if it is larger than the default. CMake uses the |
| largest value specified by any target in a component. |
| .SS LINK_INTERFACE_MULTIPLICITY_<CONFIG> |
| .sp |
| Per\-configuration repetition count for cycles of \fBSTATIC\fP libraries. |
| .sp |
| This is the configuration\-specific version of |
| \fBLINK_INTERFACE_MULTIPLICITY\fP\&. If set, this property completely |
| overrides the generic property for the named configuration. |
| .SS LINK_LIBRARIES |
| .sp |
| List of direct link dependencies. |
| .sp |
| This property specifies the list of libraries or targets which will be |
| used for linking. In addition to accepting values from the |
| \fBtarget_link_libraries()\fP command, values may be set directly on |
| any target using the \fBset_property()\fP command. |
| .sp |
| The value of this property is used by the generators to construct the |
| link rule for the target. The direct link dependencies are linked first, |
| followed by indirect dependencies from the transitive closure of the |
| direct dependencies\(aq \fBINTERFACE_LINK_LIBRARIES\fP properties. |
| See policy \fBCMP0022\fP\&. |
| .sp |
| Contents of \fBLINK_LIBRARIES\fP may use "generator expressions" with the |
| syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP manual |
| for available expressions. See the \fBcmake\-buildsystem(7)\fP manual |
| for more on defining buildsystem properties. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| A call to \fBtarget_link_libraries(<target> ...)\fP may update this |
| property on \fB<target>\fP\&. If \fB<target>\fP was not created in the same |
| directory as the call then \fBtarget_link_libraries()\fP will wrap each |
| entry with the form \fB::@(directory\-id);...;::@\fP, where the \fB::@\fP is |
| literal and the \fB(directory\-id)\fP is unspecified. |
| This tells the generators that the named libraries must be looked up in |
| the scope of the caller rather than in the scope in which the |
| \fB<target>\fP was created. Valid directory ids are stripped on export |
| by the \fBinstall(EXPORT)\fP and \fBexport()\fP commands. |
| .UNINDENT |
| .UNINDENT |
| .SS LINK_LIBRARIES_ONLY_TARGETS |
| .sp |
| New in version 3.23. |
| |
| .sp |
| Enforce that link items that can be target names are actually existing targets. |
| .sp |
| Set this property to a true value to enable additional checks on the contents |
| of the \fBLINK_LIBRARIES\fP and \fBINTERFACE_LINK_LIBRARIES\fP |
| target properties, typically populated by \fBtarget_link_libraries()\fP\&. |
| CMake will verify that link items that might be target names actually name |
| existing targets. An item is considered a possible target name if: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| it does not contain a \fB/\fP or \fB\e\fP, and |
| .IP \(bu 2 |
| it does not start in \fB\-\fP, and |
| .IP \(bu 2 |
| (for historical reasons) it does not start in \fB$\fP or \fB\(ga\fP\&. |
| .UNINDENT |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_LINK_LIBRARIES_ONLY_TARGETS\fP variable when a non\-imported |
| target is created. The property may be explicitly enabled on an imported |
| target to check its link interface. |
| .sp |
| In the following example, CMake will halt with an error at configure time |
| because \fBmiLib\fP is not a target: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(CMAKE_LINK_LIBRARIES_ONLY_TARGETS ON) |
| add_library(myLib STATIC myLib.c) |
| add_executable(myExe myExe.c) |
| target_link_libraries(myExe PRIVATE miLib) # typo for myLib |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In order to link toolchain\-provided libraries by name while still |
| enforcing \fBLINK_LIBRARIES_ONLY_TARGETS\fP, use an |
| imported |
| Interface Library with the |
| \fBIMPORTED_LIBNAME\fP target property: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(toolchain::m INTERFACE IMPORTED) |
| set_property(TARGET toolchain::m PROPERTY IMPORTED_LIBNAME "m") |
| target_link_libraries(myExe PRIVATE toolchain::m) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| See also policy \fBCMP0028\fP\&. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| If \fBINTERFACE_LINK_LIBRARIES\fP contains generator expressions, |
| its actual list of link items may depend on the type and properties of |
| the consuming target. In such cases CMake may not always detect names |
| of missing targets that only appear for specific consumers. |
| A future version of CMake with improved heuristics may start triggering |
| errors on projects accepted by previous versions of CMake. |
| .UNINDENT |
| .UNINDENT |
| .SS LINK_OPTIONS |
| .sp |
| New in version 3.13. |
| |
| .sp |
| List of options to use for the link step of shared library, module |
| and executable targets as well as the device link step. Targets that are static |
| libraries need to use the \fBSTATIC_LIBRARY_OPTIONS\fP target property. |
| .sp |
| These options are used for both normal linking and device linking |
| (see policy \fBCMP0105\fP). To control link options for normal and device |
| link steps, \fB$<HOST_LINK>\fP and \fB$<DEVICE_LINK>\fP |
| \fBgenerator expressions\fP can be used. |
| .sp |
| This property holds a semicolon\-separated list of |
| options specified so far for its target. Use the \fBtarget_link_options()\fP |
| command to append more options. |
| .sp |
| This property is initialized by the \fBLINK_OPTIONS\fP directory |
| property when a target is created, and is used by the generators to set |
| the options for the compiler. |
| .sp |
| Contents of \fBLINK_OPTIONS\fP may use "generator expressions" with the |
| syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP manual |
| for available expressions. See the \fBcmake\-buildsystem(7)\fP manual |
| for more on defining buildsystem properties. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This property must be used in preference to \fBLINK_FLAGS\fP property. |
| .UNINDENT |
| .UNINDENT |
| .SS Host And Device Specific Link Options |
| .sp |
| New in version 3.18: When a device link step is involved, which is controlled by |
| \fBCUDA_SEPARABLE_COMPILATION\fP and |
| \fBCUDA_RESOLVE_DEVICE_SYMBOLS\fP properties and policy \fBCMP0105\fP, |
| the raw options will be delivered to the host and device link steps (wrapped in |
| \fB\-Xcompiler\fP or equivalent for device link). Options wrapped with |
| \fB$<DEVICE_LINK:...>\fP |
| \fBgenerator expression\fP will be used |
| only for the device link step. Options wrapped with \fB$<HOST_LINK:...>\fP |
| \fBgenerator expression\fP will be used |
| only for the host link step. |
| |
| .SS Option De\-duplication |
| .sp |
| The final set of options used for a target is constructed by |
| accumulating options from the current target and the usage requirements of |
| its dependencies. The set of options is de\-duplicated to avoid repetition. |
| .sp |
| New in version 3.12: While beneficial for individual options, the de\-duplication step can break |
| up option groups. For example, \fB\-option A \-option B\fP becomes |
| \fB\-option A B\fP\&. One may specify a group of options using shell\-like |
| quoting along with a \fBSHELL:\fP prefix. The \fBSHELL:\fP prefix is dropped, |
| and the rest of the option string is parsed using the |
| \fBseparate_arguments()\fP \fBUNIX_COMMAND\fP mode. For example, |
| \fB"SHELL:\-option A" "SHELL:\-option B"\fP becomes \fB\-option A \-option B\fP\&. |
| |
| .SS Handling Compiler Driver Differences |
| .sp |
| To pass options to the linker tool, each compiler driver has its own syntax. |
| The \fBLINKER:\fP prefix and \fB,\fP separator can be used to specify, in a portable |
| way, options to pass to the linker tool. \fBLINKER:\fP is replaced by the |
| appropriate driver option and \fB,\fP by the appropriate driver separator. |
| The driver prefix and driver separator are given by the values of the |
| \fBCMAKE_<LANG>_LINKER_WRAPPER_FLAG\fP and |
| \fBCMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP\fP variables. |
| .sp |
| For example, \fB"LINKER:\-z,defs"\fP becomes \fB\-Xlinker \-z \-Xlinker defs\fP for |
| \fBClang\fP and \fB\-Wl,\-z,defs\fP for \fBGNU GCC\fP\&. |
| .sp |
| The \fBLINKER:\fP prefix can be specified as part of a \fBSHELL:\fP prefix |
| expression. |
| .sp |
| The \fBLINKER:\fP prefix supports, as an alternative syntax, specification of |
| arguments using the \fBSHELL:\fP prefix and space as separator. The previous |
| example then becomes \fB"LINKER:SHELL:\-z defs"\fP\&. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Specifying the \fBSHELL:\fP prefix anywhere other than at the beginning of the |
| \fBLINKER:\fP prefix is not supported. |
| .UNINDENT |
| .UNINDENT |
| .SS LINK_SEARCH_END_STATIC |
| .sp |
| End a link line such that static system libraries are used. |
| .sp |
| Some linkers support switches such as \fB\-Bstatic\fP and \fB\-Bdynamic\fP to |
| determine whether to use static or shared libraries for \fB\-lXXX\fP options. |
| CMake uses these options to set the link type for libraries whose full |
| paths are not known or (in some cases) are in implicit link |
| directories for the platform. By default CMake adds an option at the |
| end of the library list (if necessary) to set the linker search type |
| back to its starting type. This property switches the final linker |
| search type to \fB\-Bstatic\fP regardless of how it started. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_LINK_SEARCH_END_STATIC\fP if it is set |
| when a target is created. |
| .sp |
| See also \fBLINK_SEARCH_START_STATIC\fP\&. |
| .SS LINK_SEARCH_START_STATIC |
| .sp |
| Assume the linker looks for static libraries by default. |
| .sp |
| Some linkers support switches such as \fB\-Bstatic\fP and \fB\-Bdynamic\fP to |
| determine whether to use static or shared libraries for \fB\-lXXX\fP options. |
| CMake uses these options to set the link type for libraries whose full |
| paths are not known or (in some cases) are in implicit link |
| directories for the platform. By default the linker search type is |
| assumed to be \fB\-Bdynamic\fP at the beginning of the library list. This |
| property switches the assumption to \fB\-Bstatic\fP\&. It is intended for use |
| when linking an executable statically (e.g. with the GNU \fB\-static\fP |
| option). |
| .INDENT 0.0 |
| .TP |
| .B This property is initialized by the value of the variable |
| \fBCMAKE_LINK_SEARCH_START_STATIC\fP if it is set |
| when a target is created. |
| .UNINDENT |
| .sp |
| See also \fBLINK_SEARCH_END_STATIC\fP\&. |
| .SS LINK_WHAT_YOU_USE |
| .sp |
| New in version 3.7. |
| |
| .sp |
| This is a boolean option that, when set to \fBTRUE\fP, will automatically run |
| contents of variable \fBCMAKE_LINK_WHAT_YOU_USE_CHECK\fP on the target |
| after it is linked. In addition, the linker flag specified by variable |
| \fBCMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG\fP will be passed to the target |
| with the link command so that all libraries specified on the command line will |
| be linked into the target. This will result in the link producing a list of |
| libraries that provide no symbols used by this target but are being linked to |
| it. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| For now, it is only supported for \fBELF\fP platforms and is only applicable to |
| executable and shared or module library targets. This property will be |
| ignored for any other targets and configurations. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_LINK_WHAT_YOU_USE\fP variable if it is set |
| when a target is created. |
| .SS LINKER_LANGUAGE |
| .sp |
| Specifies language whose compiler will invoke the linker. |
| .sp |
| For executables, shared libraries, and modules, this sets the language |
| whose compiler is used to link the target (such as "C" or "CXX"). A |
| typical value for an executable is the language of the source file |
| providing the program entry point (main). If not set, the language |
| with the highest linker preference value is the default. Details of |
| the linker preferences are considered internal, but some limited |
| discussion can be found under the internal |
| \fBCMAKE_<LANG>_LINKER_PREFERENCE\fP variables. |
| .sp |
| If this property is not set by the user, it will be calculated at |
| generate\-time by CMake. |
| .SS LOCATION |
| .sp |
| Read\-only location of a target on disk. |
| .sp |
| For an imported target, this read\-only property returns the value of |
| the \fBLOCATION_<CONFIG>\fP property for an unspecified configuration |
| \fB<CONFIG>\fP provided by the target. |
| .sp |
| For a non\-imported target, this property is provided for compatibility |
| with CMake 2.4 and below. It was meant to get the location of an |
| executable target\(aqs output file for use in \fBadd_custom_command()\fP\&. The |
| path may contain a build\-system\-specific portion that is replaced at |
| build time with the configuration getting built (such as |
| \fB$(ConfigurationName)\fP in VS). In CMake 2.6 and above |
| \fBadd_custom_command()\fP automatically recognizes a target name in its |
| \fBCOMMAND\fP and \fBDEPENDS\fP options and computes the target location. In |
| CMake 2.8.4 and above \fBadd_custom_command()\fP recognizes |
| \fBgenerator expressions\fP |
| to refer to target locations anywhere in the command. |
| Therefore this property is not needed for creating custom commands. |
| .sp |
| Do not set properties that affect the location of a target after |
| reading this property. These include properties whose names match |
| \fB(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?\fP, |
| \fB(IMPLIB_)?(PREFIX|SUFFIX)\fP, or "LINKER_LANGUAGE". Failure to follow |
| this rule is not diagnosed and leaves the location of the target |
| undefined. |
| .SS LOCATION_<CONFIG> |
| .sp |
| Read\-only property providing a target location on disk. |
| .sp |
| A read\-only property that indicates where a target\(aqs main file is |
| located on disk for the configuration \fB<CONFIG>\fP\&. The property is |
| defined only for library and executable targets. An imported target |
| may provide a set of configurations different from that of the |
| importing project. By default CMake looks for an exact\-match but |
| otherwise uses an arbitrary available configuration. Use the |
| \fBMAP_IMPORTED_CONFIG_<CONFIG>\fP property to map imported |
| configurations explicitly. |
| .sp |
| Do not set properties that affect the location of a target after |
| reading this property. These include properties whose names match |
| \fB(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?\fP, |
| \fB(IMPLIB_)?(PREFIX|SUFFIX)\fP, or \fBLINKER_LANGUAGE\fP\&. |
| Failure to follow this rule is not diagnosed and leaves |
| the location of the target undefined. |
| .SS MACHO_COMPATIBILITY_VERSION |
| .sp |
| New in version 3.17. |
| |
| .sp |
| What compatibility version number is this target for Mach\-O binaries. |
| .sp |
| For shared libraries on Mach\-O systems (e.g. macOS, iOS) |
| the \fBMACHO_COMPATIBILITY_VERSION\fP property corresponds to the |
| \fIcompatibility version\fP and \fBMACHO_CURRENT_VERSION\fP corresponds to |
| the \fIcurrent version\fP\&. These are both embedded in the shared library binary |
| and can be checked with the \fBotool \-L <binary>\fP command. |
| .sp |
| It should be noted that the \fBMACHO_CURRENT_VERSION\fP and |
| \fBMACHO_COMPATIBILITY_VERSION\fP properties do not affect the file |
| names or version\-related symlinks that CMake generates for the library. |
| The \fBVERSION\fP and \fBSOVERSION\fP target properties still |
| control the file and symlink names. The \fBinstall_name\fP is also still |
| controlled by \fBSOVERSION\fP\&. |
| .sp |
| When \fBMACHO_CURRENT_VERSION\fP and \fBMACHO_COMPATIBILITY_VERSION\fP |
| are not given, \fBVERSION\fP and \fBSOVERSION\fP are used for |
| the version details to be embedded in the binaries respectively. |
| The \fBMACHO_CURRENT_VERSION\fP and \fBMACHO_COMPATIBILITY_VERSION\fP |
| properties only need to be given if the project needs to decouple the file |
| and symlink naming from the version details embedded in the binaries |
| (e.g. to match libtool conventions). |
| .SS MACHO_CURRENT_VERSION |
| .sp |
| New in version 3.17. |
| |
| .sp |
| What current version number is this target for Mach\-O binaries. |
| .sp |
| For shared libraries on Mach\-O systems (e.g. macOS, iOS) |
| the \fBMACHO_COMPATIBILITY_VERSION\fP property corresponds to the |
| \fIcompatibility version\fP and \fBMACHO_CURRENT_VERSION\fP corresponds to the |
| \fIcurrent version\fP\&. These are both embedded in the shared library binary |
| and can be checked with the \fBotool \-L <binary>\fP command. |
| .sp |
| It should be noted that the \fBMACHO_CURRENT_VERSION\fP and |
| \fBMACHO_COMPATIBILITY_VERSION\fP properties do not affect the file |
| names or version\-related symlinks that CMake generates for the library. |
| The \fBVERSION\fP and \fBSOVERSION\fP target properties still |
| control the file and symlink names. The \fBinstall_name\fP is also still |
| controlled by \fBSOVERSION\fP\&. |
| .sp |
| When \fBMACHO_CURRENT_VERSION\fP and \fBMACHO_COMPATIBILITY_VERSION\fP |
| are not given, \fBVERSION\fP and \fBSOVERSION\fP are used for |
| the version details to be embedded in the binaries respectively. |
| The \fBMACHO_CURRENT_VERSION\fP and \fBMACHO_COMPATIBILITY_VERSION\fP |
| properties only need to be given if the project needs to decouple the file |
| and symlink naming from the version details embedded in the binaries |
| (e.g. to match libtool conventions). |
| .SS MACOSX_BUNDLE |
| .sp |
| Build an executable as an Application Bundle on macOS or iOS. |
| .sp |
| When this property is set to \fBTRUE\fP the executable when built on macOS |
| or iOS will be created as an application bundle. This makes it |
| a GUI executable that can be launched from the Finder. See the |
| \fBMACOSX_BUNDLE_INFO_PLIST\fP target property for information about |
| creation of the \fBInfo.plist\fP file for the application bundle. |
| This property is initialized by the value of the variable |
| \fBCMAKE_MACOSX_BUNDLE\fP if it is set when a target is created. |
| .SS MACOSX_BUNDLE_INFO_PLIST |
| .sp |
| Specify a custom \fBInfo.plist\fP template for a macOS and iOS Application Bundle. |
| .sp |
| An executable target with \fBMACOSX_BUNDLE\fP enabled will be built as an |
| application bundle on macOS. By default its \fBInfo.plist\fP file is created |
| by configuring a template called \fBMacOSXBundleInfo.plist.in\fP located in the |
| \fBCMAKE_MODULE_PATH\fP\&. This property specifies an alternative template |
| file name which may be a full path. |
| .sp |
| The following target properties may be set to specify content to be |
| configured into the file: |
| .INDENT 0.0 |
| .TP |
| .B \fBMACOSX_BUNDLE_BUNDLE_NAME\fP |
| Sets \fBCFBundleName\fP\&. |
| .TP |
| .B \fBMACOSX_BUNDLE_BUNDLE_VERSION\fP |
| Sets \fBCFBundleVersion\fP\&. |
| .TP |
| .B \fBMACOSX_BUNDLE_COPYRIGHT\fP |
| Sets \fBNSHumanReadableCopyright\fP\&. |
| .TP |
| .B \fBMACOSX_BUNDLE_GUI_IDENTIFIER\fP |
| Sets \fBCFBundleIdentifier\fP\&. |
| .TP |
| .B \fBMACOSX_BUNDLE_ICON_FILE\fP |
| Sets \fBCFBundleIconFile\fP\&. |
| .TP |
| .B \fBMACOSX_BUNDLE_INFO_STRING\fP |
| Sets \fBCFBundleGetInfoString\fP\&. |
| .TP |
| .B \fBMACOSX_BUNDLE_LONG_VERSION_STRING\fP |
| Sets \fBCFBundleLongVersionString\fP\&. |
| .TP |
| .B \fBMACOSX_BUNDLE_SHORT_VERSION_STRING\fP |
| Sets \fBCFBundleShortVersionString\fP\&. |
| .UNINDENT |
| .sp |
| CMake variables of the same name may be set to affect all targets in a |
| directory that do not have each specific property set. If a custom |
| \fBInfo.plist\fP is specified by this property it may of course hard\-code |
| all the settings instead of using the target properties. |
| .SS MACOSX_FRAMEWORK_INFO_PLIST |
| .sp |
| Specify a custom \fBInfo.plist\fP template for a macOS and iOS Framework. |
| .sp |
| A library target with \fBFRAMEWORK\fP enabled will be built as a |
| framework on macOS. By default its \fBInfo.plist\fP file is created by |
| configuring a template called \fBMacOSXFrameworkInfo.plist.in\fP located in the |
| \fBCMAKE_MODULE_PATH\fP\&. This property specifies an alternative template |
| file name which may be a full path. |
| .sp |
| The following target properties may be set to specify content to be |
| configured into the file: |
| .INDENT 0.0 |
| .TP |
| .B \fBMACOSX_FRAMEWORK_BUNDLE_VERSION\fP |
| Sets \fBCFBundleVersion\fP\&. |
| .TP |
| .B \fBMACOSX_FRAMEWORK_ICON_FILE\fP |
| Sets \fBCFBundleIconFile\fP\&. |
| .TP |
| .B \fBMACOSX_FRAMEWORK_IDENTIFIER\fP |
| Sets \fBCFBundleIdentifier\fP\&. |
| .TP |
| .B \fBMACOSX_FRAMEWORK_SHORT_VERSION_STRING\fP |
| Sets \fBCFBundleShortVersionString\fP\&. |
| .UNINDENT |
| .sp |
| CMake variables of the same name may be set to affect all targets in a |
| directory that do not have each specific property set. If a custom |
| \fBInfo.plist\fP is specified by this property it may of course hard\-code |
| all the settings instead of using the target properties. |
| .SS MACOSX_RPATH |
| .sp |
| Whether this target on macOS or iOS is located at runtime using rpaths. |
| .sp |
| When this property is set to \fBTRUE\fP, the directory portion of |
| the \fBinstall_name\fP field of this shared library will be \fB@rpath\fP |
| unless overridden by \fBINSTALL_NAME_DIR\fP\&. This indicates |
| the shared library is to be found at runtime using runtime |
| paths (rpaths). |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_MACOSX_RPATH\fP if it is set when a target is |
| created. |
| .sp |
| Runtime paths will also be embedded in binaries using this target and |
| can be controlled by the \fBINSTALL_RPATH\fP target property on |
| the target linking to this target. |
| .sp |
| Policy \fBCMP0042\fP was introduced to change the default value of |
| \fBMACOSX_RPATH\fP to \fBTRUE\fP\&. This is because use of \fB@rpath\fP is a |
| more flexible and powerful alternative to \fB@executable_path\fP and |
| \fB@loader_path\fP\&. |
| .SS MANUALLY_ADDED_DEPENDENCIES |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Get manually added dependencies to other top\-level targets. |
| .sp |
| This read\-only property can be used to query all dependencies that |
| were added for this target with the \fBadd_dependencies()\fP |
| command. |
| .SS MAP_IMPORTED_CONFIG_<CONFIG> |
| .sp |
| Map from project configuration to |
| imported target\(aqs configuration. |
| .sp |
| Set this to the list of configurations of an imported target that may |
| be used for the current project\(aqs \fB<CONFIG>\fP configuration. Targets |
| imported from another project may not provide the same set of |
| configuration names available in the current project. Setting this |
| property tells CMake what imported configurations are suitable for use |
| when building the \fB<CONFIG>\fP configuration. The first configuration in |
| the list found to be provided by the imported target (i.e. via |
| \fBIMPORTED_LOCATION_<CONFIG>\fP for the mapped\-to \fB<CONFIG>\fP) |
| is selected. As a special case, an empty list element refers to the |
| configuration\-less imported target location |
| (i.e. \fBIMPORTED_LOCATION\fP). |
| .sp |
| If this property is set and no matching configurations are available, |
| then the imported target is considered to be not found. This property |
| is ignored for non\-imported targets. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_MAP_IMPORTED_CONFIG_<CONFIG>\fP variable if it is set when a |
| target is created. |
| .SS Example |
| .sp |
| For example creating imported C++ library \fBfoo\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(foo STATIC IMPORTED) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Use \fBfoo_debug\fP path for \fBDebug\fP build type: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property( |
| TARGET foo APPEND PROPERTY IMPORTED_CONFIGURATIONS DEBUG |
| ) |
| |
| set_target_properties(foo PROPERTIES |
| IMPORTED_LINK_INTERFACE_LANGUAGES_DEBUG "CXX" |
| IMPORTED_LOCATION_DEBUG "${foo_debug}" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Use \fBfoo_release\fP path for \fBRelease\fP build type: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property( |
| TARGET foo APPEND PROPERTY IMPORTED_CONFIGURATIONS RELEASE |
| ) |
| |
| set_target_properties(foo PROPERTIES |
| IMPORTED_LINK_INTERFACE_LANGUAGES_RELEASE "CXX" |
| IMPORTED_LOCATION_RELEASE "${foo_release}" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Use \fBRelease\fP version of library for \fBMinSizeRel\fP and \fBRelWithDebInfo\fP |
| build types: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_target_properties(foo PROPERTIES |
| MAP_IMPORTED_CONFIG_MINSIZEREL Release |
| MAP_IMPORTED_CONFIG_RELWITHDEBINFO Release |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS MSVC_RUNTIME_LIBRARY |
| .sp |
| New in version 3.15. |
| |
| .sp |
| Select the MSVC runtime library for use by compilers targeting the MSVC ABI. |
| .sp |
| The allowed values are: |
| .INDENT 0.0 |
| .TP |
| .B \fBMultiThreaded\fP |
| Compile with \fB\-MT\fP or equivalent flag(s) to use a multi\-threaded |
| statically\-linked runtime library. |
| .TP |
| .B \fBMultiThreadedDLL\fP |
| Compile with \fB\-MD\fP or equivalent flag(s) to use a multi\-threaded |
| dynamically\-linked runtime library. |
| .TP |
| .B \fBMultiThreadedDebug\fP |
| Compile with \fB\-MTd\fP or equivalent flag(s) to use a multi\-threaded |
| statically\-linked runtime library. |
| .TP |
| .B \fBMultiThreadedDebugDLL\fP |
| Compile with \fB\-MDd\fP or equivalent flag(s) to use a multi\-threaded |
| dynamically\-linked runtime library. |
| .UNINDENT |
| .sp |
| The value is ignored on non\-MSVC compilers but an unsupported value will |
| be rejected as an error when using a compiler targeting the MSVC ABI. |
| .sp |
| The value may also be the empty string (\fB""\fP) in which case no runtime |
| library selection flag will be added explicitly by CMake. Note that with |
| Visual Studio Generators the native build system may choose to |
| add its own default runtime library selection flag. |
| .sp |
| Use \fBgenerator expressions\fP to |
| support per\-configuration specification. For example, the code: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_executable(foo foo.c) |
| set_property(TARGET foo PROPERTY |
| MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| selects for the target \fBfoo\fP a multi\-threaded statically\-linked runtime |
| library with or without debug information depending on the configuration. |
| .sp |
| If this property is not set then CMake uses the default value |
| \fBMultiThreaded$<$<CONFIG:Debug>:Debug>DLL\fP to select a MSVC runtime library. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This property has effect only when policy \fBCMP0091\fP is set to \fBNEW\fP |
| prior to the first \fBproject()\fP or \fBenable_language()\fP command |
| that enables a language using a compiler targeting the MSVC ABI. |
| .UNINDENT |
| .UNINDENT |
| .SS NAME |
| .sp |
| Logical name for the target. |
| .sp |
| Read\-only logical name for the target as used by CMake. |
| .SS NO_SONAME |
| .sp |
| Whether to set \fBsoname\fP when linking a shared library. |
| .sp |
| Enable this boolean property if a generated \fBSHARED\fP library |
| should not have \fBsoname\fP set. Default is to set \fBsoname\fP on all |
| shared libraries as long as the platform supports it. |
| Generally, use this property only for leaf private libraries or |
| plugins. If you use it on normal shared libraries which other targets |
| link against, on some platforms a linker will insert a full path to |
| the library (as specified at link time) into the dynamic section of |
| the dependent binary. Therefore, once installed, dynamic loader may |
| eventually fail to locate the library for the binary. |
| .SS NO_SYSTEM_FROM_IMPORTED |
| .sp |
| Do not treat include directories from the interfaces of consumed |
| imported targets as \fBSYSTEM\fP\&. |
| .sp |
| The contents of the \fBINTERFACE_INCLUDE_DIRECTORIES\fP target property |
| of imported targets are treated as \fBSYSTEM\fP includes by default. If this |
| property is enabled on a target, compilation of sources in that target will |
| not treat the contents of the \fBINTERFACE_INCLUDE_DIRECTORIES\fP of consumed |
| imported targets as system includes. Either way, entries of |
| \fBINTERFACE_SYSTEM_INCLUDE_DIRECTORIES\fP are not affected, |
| and will always be treated as \fBSYSTEM\fP include directories. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_NO_SYSTEM_FROM_IMPORTED\fP variable if it is set when a target |
| is created. |
| .sp |
| See the \fBIMPORTED_NO_SYSTEM\fP target property to set this behavior |
| on the target providing the include directories rather than consuming them. |
| .SS OBJC_EXTENSIONS |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Boolean specifying whether compiler specific extensions are requested. |
| .sp |
| This property specifies whether compiler specific extensions should be |
| used. For some compilers, this results in adding a flag such |
| as \fB\-std=gnu11\fP instead of \fB\-std=c11\fP to the compile line. This |
| property is \fBON\fP by default. The basic OBJC standard level is |
| controlled by the \fBOBJC_STANDARD\fP target property. |
| .sp |
| If the property is not set, and the project has set the \fBC_EXTENSIONS\fP, |
| the value of \fBC_EXTENSIONS\fP is set for \fI\%OBJC_EXTENSIONS\fP\&. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_OBJC_EXTENSIONS\fP variable if set when a target is created |
| and otherwise by the value of |
| \fBCMAKE_OBJC_EXTENSIONS_DEFAULT\fP |
| (see \fBCMP0128\fP). |
| .SS OBJC_STANDARD |
| .sp |
| New in version 3.16. |
| |
| .sp |
| The OBJC standard whose features are requested to build this target. |
| .sp |
| This property specifies the OBJC standard whose features are requested |
| to build this target. For some compilers, this results in adding a |
| flag such as \fB\-std=gnu11\fP to the compile line. |
| .sp |
| Supported values are: |
| .INDENT 0.0 |
| .TP |
| .B \fB90\fP |
| Objective C89/C90 |
| .TP |
| .B \fB99\fP |
| Objective C99 |
| .TP |
| .B \fB11\fP |
| Objective C11 |
| .UNINDENT |
| .sp |
| If the value requested does not result in a compile flag being added for |
| the compiler in use, a previous standard flag will be added instead. This |
| means that using: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET tgt PROPERTY OBJC_STANDARD 11) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| with a compiler which does not support \fB\-std=gnu11\fP or an equivalent |
| flag will not result in an error or warning, but will instead add the |
| \fB\-std=gnu99\fP or \fB\-std=gnu90\fP flag if supported. This "decay" behavior may |
| be controlled with the \fBOBJC_STANDARD_REQUIRED\fP target property. |
| Additionally, the \fBOBJC_EXTENSIONS\fP target property may be used to |
| control whether compiler\-specific extensions are enabled on a per\-target basis. |
| .sp |
| If the property is not set, and the project has set the \fBC_STANDARD\fP, |
| the value of \fBC_STANDARD\fP is set for \fI\%OBJC_STANDARD\fP\&. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_OBJC_STANDARD\fP variable if it is set when a target |
| is created. |
| .SS OBJC_STANDARD_REQUIRED |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Boolean describing whether the value of \fBOBJC_STANDARD\fP is a requirement. |
| .sp |
| If this property is set to \fBON\fP, then the value of the |
| \fBOBJC_STANDARD\fP target property is treated as a requirement. If this |
| property is \fBOFF\fP or unset, the \fBOBJC_STANDARD\fP target property is |
| treated as optional and may "decay" to a previous standard if the requested is |
| not available. |
| .sp |
| If the property is not set, and the project has set the \fBC_STANDARD_REQUIRED\fP, |
| the value of \fBC_STANDARD_REQUIRED\fP is set for \fI\%OBJC_STANDARD_REQUIRED\fP\&. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_OBJC_STANDARD_REQUIRED\fP variable if it is set when a |
| target is created. |
| .SS OBJCXX_EXTENSIONS |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Boolean specifying whether compiler specific extensions are requested. |
| .sp |
| This property specifies whether compiler specific extensions should be |
| used. For some compilers, this results in adding a flag such |
| as \fB\-std=gnu++11\fP instead of \fB\-std=c++11\fP to the compile line. This |
| property is \fBON\fP by default. The basic ObjC++ standard level is |
| controlled by the \fBOBJCXX_STANDARD\fP target property. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| If the property is not set, and the project has set the \fBCXX_EXTENSIONS\fP, |
| the value of \fBCXX_EXTENSIONS\fP is set for \fI\%OBJCXX_EXTENSIONS\fP\&. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_OBJCXX_EXTENSIONS\fP variable if set when a target is |
| created and otherwise by the value of |
| \fBCMAKE_OBJCXX_EXTENSIONS_DEFAULT\fP |
| (see \fBCMP0128\fP). |
| .SS OBJCXX_STANDARD |
| .sp |
| New in version 3.16. |
| |
| .sp |
| The ObjC++ standard whose features are requested to build this target. |
| .sp |
| This property specifies the ObjC++ standard whose features are requested |
| to build this target. For some compilers, this results in adding a |
| flag such as \fB\-std=gnu++11\fP to the compile line. |
| .sp |
| Supported values are: |
| .INDENT 0.0 |
| .TP |
| .B \fB98\fP |
| Objective C++98 |
| .TP |
| .B \fB11\fP |
| Objective C++11 |
| .TP |
| .B \fB14\fP |
| Objective C++14 |
| .TP |
| .B \fB17\fP |
| Objective C++17 |
| .TP |
| .B \fB20\fP |
| Objective C++20 |
| .TP |
| .B \fB23\fP |
| New in version 3.20. |
| |
| .sp |
| Objective C++23 |
| .UNINDENT |
| .sp |
| If the value requested does not result in a compile flag being added for |
| the compiler in use, a previous standard flag will be added instead. This |
| means that using: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET tgt PROPERTY OBJCXX_STANDARD 11) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| with a compiler which does not support \fB\-std=gnu++11\fP or an equivalent |
| flag will not result in an error or warning, but will instead add the |
| \fB\-std=gnu++98\fP flag if supported. This "decay" behavior may be controlled |
| with the \fBOBJCXX_STANDARD_REQUIRED\fP target property. |
| Additionally, the \fBOBJCXX_EXTENSIONS\fP target property may be used to |
| control whether compiler\-specific extensions are enabled on a per\-target basis. |
| .sp |
| If the property is not set, and the project has set the \fBCXX_STANDARD\fP, |
| the value of \fBCXX_STANDARD\fP is set for \fI\%OBJCXX_STANDARD\fP\&. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_OBJCXX_STANDARD\fP variable if it is set when a target |
| is created. |
| .SS OBJCXX_STANDARD_REQUIRED |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Boolean describing whether the value of \fBOBJCXX_STANDARD\fP is a requirement. |
| .sp |
| If this property is set to \fBON\fP, then the value of the |
| \fBOBJCXX_STANDARD\fP target property is treated as a requirement. If this |
| property is \fBOFF\fP or unset, the \fBOBJCXX_STANDARD\fP target property is |
| treated as optional and may "decay" to a previous standard if the requested is |
| not available. |
| .sp |
| If the property is not set, and the project has set the \fBCXX_STANDARD_REQUIRED\fP, |
| the value of \fBCXX_STANDARD_REQUIRED\fP is set for \fI\%OBJCXX_STANDARD_REQUIRED\fP\&. |
| .sp |
| See the \fBcmake\-compile\-features(7)\fP manual for information on |
| compile features and a list of supported compilers. |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_OBJCXX_STANDARD_REQUIRED\fP variable if it is set when a |
| target is created. |
| .SS OPTIMIZE_DEPENDENCIES |
| .sp |
| New in version 3.19. |
| |
| .sp |
| Activates dependency optimization of static and object libraries. |
| .sp |
| When this property is set to true, some dependencies for a static or object |
| library may be removed at generation time if they are not necessary to build |
| the library, since static and object libraries don\(aqt actually link against |
| anything. |
| .sp |
| If a static or object library has dependency optimization enabled, it first |
| discards all dependencies. Then, it looks through all of the direct and |
| indirect dependencies that it initially had, and adds them back if they meet |
| any of the following criteria: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| The dependency was added to the library by \fBadd_dependencies()\fP\&. |
| .IP \(bu 2 |
| The dependency was added to the library through a source file in the library |
| generated by a custom command that uses the dependency. |
| .IP \(bu 2 |
| The dependency has any \fBPRE_BUILD\fP, \fBPRE_LINK\fP, or \fBPOST_BUILD\fP custom |
| commands associated with it. |
| .IP \(bu 2 |
| The dependency contains any source files that were generated by a custom |
| command. |
| .IP \(bu 2 |
| The dependency contains any languages which produce side effects that are |
| relevant to the library. Currently, all languages except C, C++, Objective\-C, |
| Objective\-C++, assembly, and CUDA are assumed to produce side effects. |
| However, side effects from one language are assumed not to be relevant to |
| another (for example, a Fortran library is assumed to not have any side |
| effects that are relevant for a Swift library.) |
| .UNINDENT |
| .sp |
| As an example, assume you have a static Fortran library which depends on a |
| static C library, which in turn depends on a static Fortran library. The |
| top\-level Fortran library has optimization enabled, but the middle C library |
| does not. If you build the top Fortran library, the bottom Fortran library will |
| also build, but not the middle C library, since the C library does not have any |
| side effects that are relevant for the Fortran library. However, if you build |
| the middle C library, the bottom Fortran library will also build, even though |
| it does not have any side effects that are relevant to the C library, since the |
| C library does not have optimization enabled. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_OPTIMIZE_DEPENDENCIES\fP variable when the target is created. |
| .SS OSX_ARCHITECTURES |
| .sp |
| Target specific architectures for macOS. |
| .sp |
| The \fBOSX_ARCHITECTURES\fP property sets the target binary architecture for |
| targets on macOS (\fB\-arch\fP). This property is initialized by the value of the |
| variable \fBCMAKE_OSX_ARCHITECTURES\fP if it is set when a target is |
| created. Use \fBOSX_ARCHITECTURES_<CONFIG>\fP to set the binary |
| architectures on a per\-configuration basis, where \fB<CONFIG>\fP is an |
| upper\-case name (e.g. \fBOSX_ARCHITECTURES_DEBUG\fP). |
| .SS OSX_ARCHITECTURES_<CONFIG> |
| .sp |
| Per\-configuration macOS and iOS binary architectures for a target. |
| .sp |
| This property is the configuration\-specific version of |
| \fBOSX_ARCHITECTURES\fP\&. |
| .SS OUTPUT_NAME |
| .sp |
| Output name for target files. |
| .sp |
| This sets the base name for output files created for an executable or |
| library target. If not set, the logical target name is used by |
| default during generation. The value is not set by default during |
| configuration. |
| .sp |
| Contents of \fBOUTPUT_NAME\fP and the variants listed below may use |
| \fBgenerator expressions\fP\&. |
| .sp |
| See also the variants: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBOUTPUT_NAME_<CONFIG>\fP |
| .IP \(bu 2 |
| \fBARCHIVE_OUTPUT_NAME_<CONFIG>\fP |
| .IP \(bu 2 |
| \fBARCHIVE_OUTPUT_NAME\fP |
| .IP \(bu 2 |
| \fBLIBRARY_OUTPUT_NAME_<CONFIG>\fP |
| .IP \(bu 2 |
| \fBLIBRARY_OUTPUT_NAME\fP |
| .IP \(bu 2 |
| \fBRUNTIME_OUTPUT_NAME_<CONFIG>\fP |
| .IP \(bu 2 |
| \fBRUNTIME_OUTPUT_NAME\fP |
| .UNINDENT |
| .SS OUTPUT_NAME_<CONFIG> |
| .sp |
| Per\-configuration target file base name. |
| .sp |
| This is the configuration\-specific version of the \fBOUTPUT_NAME\fP |
| target property. |
| .SS PCH_WARN_INVALID |
| .sp |
| New in version 3.18. |
| |
| .sp |
| When this property is set to true, the precompile header compiler options |
| will contain a compiler flag which should warn about invalid precompiled |
| headers e.g. \fB\-Winvalid\-pch\fP for GNU compiler. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_PCH_WARN_INVALID\fP variable if it is set when a target is |
| created. If that variable is not set, the property defaults to \fBON\fP\&. |
| .SS PCH_INSTANTIATE_TEMPLATES |
| .sp |
| New in version 3.19. |
| |
| .sp |
| When this property is set to true, the precompiled header compiler options |
| will contain a flag to instantiate templates during the generation of the PCH |
| if supported. This can significantly improve compile times. Supported in Clang |
| since version 11. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_PCH_INSTANTIATE_TEMPLATES\fP variable if it is set when a target |
| is created. If that variable is not set, the property defaults to \fBON\fP\&. |
| .SS PDB_NAME |
| .sp |
| Output name for the MS debug symbol \fB\&.pdb\fP file generated by the |
| linker for an executable or shared library target. |
| .sp |
| This property specifies the base name for the debug symbols file. |
| If not set, the \fBOUTPUT_NAME\fP target property value or |
| logical target name is used by default. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This property does not apply to STATIC library targets because no linker |
| is invoked to produce them so they have no linker\-generated \fB\&.pdb\fP file |
| containing debug symbols. |
| .sp |
| The linker\-generated program database files are specified by the |
| \fB/pdb\fP linker flag and are not the same as compiler\-generated |
| program database files specified by the \fB/Fd\fP compiler flag. |
| Use the \fBCOMPILE_PDB_NAME\fP property to specify the latter. |
| .UNINDENT |
| .UNINDENT |
| .SS PDB_NAME_<CONFIG> |
| .sp |
| Per\-configuration output name for the MS debug symbol \fB\&.pdb\fP file |
| generated by the linker for an executable or shared library target. |
| .sp |
| This is the configuration\-specific version of \fBPDB_NAME\fP\&. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This property does not apply to STATIC library targets because no linker |
| is invoked to produce them so they have no linker\-generated \fB\&.pdb\fP file |
| containing debug symbols. |
| .sp |
| The linker\-generated program database files are specified by the |
| \fB/pdb\fP linker flag and are not the same as compiler\-generated |
| program database files specified by the \fB/Fd\fP compiler flag. |
| Use the \fBCOMPILE_PDB_NAME_<CONFIG>\fP property to specify the latter. |
| .UNINDENT |
| .UNINDENT |
| .SS PDB_OUTPUT_DIRECTORY |
| .sp |
| Output directory for the MS debug symbols \fB\&.pdb\fP file |
| generated by the linker for an executable or shared library target. |
| .sp |
| This property specifies the directory into which the MS debug symbols |
| will be placed by the linker. The property value may use |
| \fBgenerator expressions\fP\&. |
| Multi\-configuration generators append a per\-configuration |
| subdirectory to the specified directory unless a generator expression |
| is used. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_PDB_OUTPUT_DIRECTORY\fP variable if it is |
| set when a target is created. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This property does not apply to STATIC library targets because no linker |
| is invoked to produce them so they have no linker\-generated \fB\&.pdb\fP file |
| containing debug symbols. |
| .sp |
| The linker\-generated program database files are specified by the |
| \fB/pdb\fP linker flag and are not the same as compiler\-generated |
| program database files specified by the \fB/Fd\fP compiler flag. |
| Use the \fBCOMPILE_PDB_OUTPUT_DIRECTORY\fP property to specify the latter. |
| .UNINDENT |
| .UNINDENT |
| .SS PDB_OUTPUT_DIRECTORY_<CONFIG> |
| .sp |
| Per\-configuration output directory for the MS debug symbol \fB\&.pdb\fP file |
| generated by the linker for an executable or shared library target. |
| .sp |
| This is a per\-configuration version of \fBPDB_OUTPUT_DIRECTORY\fP, |
| but multi\-configuration generators (Visual Studio Generators, |
| \fBXcode\fP) do NOT append a |
| per\-configuration subdirectory to the specified directory. This |
| property is initialized by the value of the |
| \fBCMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG>\fP variable if it is |
| set when a target is created. |
| .sp |
| Contents of \fBPDB_OUTPUT_DIRECTORY_<CONFIG>\fP may use |
| \fBgenerator expressions\fP\&. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This property does not apply to STATIC library targets because no linker |
| is invoked to produce them so they have no linker\-generated \fB\&.pdb\fP file |
| containing debug symbols. |
| .sp |
| The linker\-generated program database files are specified by the |
| \fB/pdb\fP linker flag and are not the same as compiler\-generated |
| program database files specified by the \fB/Fd\fP compiler flag. |
| Use the \fBCOMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>\fP property to specify the latter. |
| .UNINDENT |
| .UNINDENT |
| .SS POSITION_INDEPENDENT_CODE |
| .sp |
| Whether to create a position\-independent target |
| .sp |
| The \fBPOSITION_INDEPENDENT_CODE\fP property determines whether position |
| independent executables or shared libraries will be created. This |
| property is \fBTrue\fP by default for \fBSHARED\fP and \fBMODULE\fP library |
| targets and \fBFalse\fP otherwise. This property is initialized by the value |
| of the \fBCMAKE_POSITION_INDEPENDENT_CODE\fP variable if it is set |
| when a target is created. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| For executable targets, the link step is controlled by the \fBCMP0083\fP |
| policy and the \fBCheckPIESupported\fP module. |
| .UNINDENT |
| .UNINDENT |
| .SS PRECOMPILE_HEADERS |
| .sp |
| New in version 3.16. |
| |
| .sp |
| List of header files to precompile. |
| .sp |
| This property holds a semicolon\-separated list |
| of header files to precompile specified so far for its target. |
| Use the \fBtarget_precompile_headers()\fP command to append more header |
| files. |
| .sp |
| This property supports |
| \fBgenerator expressions\fP\&. |
| .SS PRECOMPILE_HEADERS_REUSE_FROM |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Target from which to reuse the precompiled headers build artifact. |
| .sp |
| See the second signature of \fBtarget_precompile_headers()\fP command |
| for more detailed information. |
| .SS PREFIX |
| .sp |
| What comes before the library name. |
| .sp |
| A target property that can be set to override the prefix (such as |
| \fBlib\fP) on a library name. |
| .SS PRIVATE_HEADER |
| .sp |
| Specify private header files in a \fBFRAMEWORK\fP shared library target. |
| .sp |
| Shared library targets marked with the \fBFRAMEWORK\fP property generate |
| frameworks on macOS, iOS and normal shared libraries on other platforms. |
| This property may be set to a list of header files to be placed in the |
| PrivateHeaders directory inside the framework folder. On non\-Apple |
| platforms these headers may be installed using the \fBPRIVATE_HEADER\fP |
| option to the \fBinstall(TARGETS)\fP command. |
| .SS PROJECT_LABEL |
| .sp |
| Change the name of a target in an IDE. |
| .sp |
| Can be used to change the name of the target in an IDE like Visual |
| Studio. |
| .SS PUBLIC_HEADER |
| .sp |
| Specify public header files in a \fBFRAMEWORK\fP shared library target. |
| .sp |
| Shared library targets marked with the \fBFRAMEWORK\fP property generate |
| frameworks on macOS, iOS and normal shared libraries on other platforms. |
| This property may be set to a list of header files to be placed in the |
| \fBHeaders\fP directory inside the framework folder. On non\-Apple platforms |
| these headers may be installed using the \fBPUBLIC_HEADER\fP option to the |
| \fBinstall(TARGETS)\fP command. |
| .SS RESOURCE |
| .sp |
| Specify resource files in a \fBFRAMEWORK\fP or \fBBUNDLE\fP\&. |
| .sp |
| Target marked with the \fBFRAMEWORK\fP or \fBBUNDLE\fP property |
| generate framework or application bundle (both macOS and iOS is supported) |
| or normal shared libraries on other platforms. |
| This property may be set to a list of files to be placed in the corresponding |
| directory (eg. \fBResources\fP directory for macOS) inside the bundle. |
| On non\-Apple platforms these files may be installed using the \fBRESOURCE\fP |
| option to the \fBinstall(TARGETS)\fP command. |
| .sp |
| Following example of Application Bundle: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_executable(ExecutableTarget |
| addDemo.c |
| resourcefile.txt |
| appresourcedir/appres.txt) |
| |
| target_link_libraries(ExecutableTarget heymath mul) |
| |
| set(RESOURCE_FILES |
| resourcefile.txt |
| appresourcedir/appres.txt) |
| |
| set_target_properties(ExecutableTarget PROPERTIES |
| MACOSX_BUNDLE TRUE |
| MACOSX_FRAMEWORK_IDENTIFIER org.cmake.ExecutableTarget |
| RESOURCE "${RESOURCE_FILES}") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| will produce flat structure for iOS systems: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExecutableTarget.app |
| appres.txt |
| ExecutableTarget |
| Info.plist |
| resourcefile.txt |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| For macOS systems it will produce following directory structure: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExecutableTarget.app/ |
| Contents |
| Info.plist |
| MacOS |
| ExecutableTarget |
| Resources |
| appres.txt |
| resourcefile.txt |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| For Linux, such CMake script produce following files: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ExecutableTarget |
| Resources |
| appres.txt |
| resourcefile.txt |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS RULE_LAUNCH_COMPILE |
| .sp |
| Specify a launcher for compile rules. |
| .sp |
| See the global property of the same name for details. This overrides |
| the global and directory property for a target. |
| .SS RULE_LAUNCH_CUSTOM |
| .sp |
| Specify a launcher for custom rules. |
| .sp |
| See the global property of the same name for details. This overrides |
| the global and directory property for a target. |
| .SS RULE_LAUNCH_LINK |
| .sp |
| Specify a launcher for link rules. |
| .sp |
| See the global property of the same name for details. This overrides |
| the global and directory property for a target. |
| .SS RUNTIME_OUTPUT_DIRECTORY |
| .sp |
| Output directory in which to build RUNTIME target files. |
| .sp |
| This property specifies the directory into which runtime target files |
| should be built. The property value may use |
| \fBgenerator expressions\fP\&. |
| Multi\-configuration generators (Visual Studio, |
| \fBXcode\fP, \fBNinja Multi\-Config\fP) append a |
| per\-configuration subdirectory to the specified directory unless a generator |
| expression is used. |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_RUNTIME_OUTPUT_DIRECTORY\fP variable if it is set when a target is created. |
| .sp |
| See also the \fBRUNTIME_OUTPUT_DIRECTORY_<CONFIG>\fP target property. |
| .SS RUNTIME_OUTPUT_DIRECTORY_<CONFIG> |
| .sp |
| Per\-configuration output directory for |
| RUNTIME target files. |
| .sp |
| This is a per\-configuration version of the |
| \fBRUNTIME_OUTPUT_DIRECTORY\fP target property, but |
| multi\-configuration generators (Visual Studio Generators, |
| \fBXcode\fP) do NOT append a |
| per\-configuration subdirectory to the specified directory. This |
| property is initialized by the value of the |
| \fBCMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG>\fP variable if |
| it is set when a target is created. |
| .sp |
| Contents of \fBRUNTIME_OUTPUT_DIRECTORY_<CONFIG>\fP may use |
| \fBgenerator expressions\fP\&. |
| .SS RUNTIME_OUTPUT_NAME |
| .sp |
| Output name for RUNTIME target files. |
| .sp |
| This property specifies the base name for runtime target files. It |
| overrides \fBOUTPUT_NAME\fP and \fBOUTPUT_NAME_<CONFIG>\fP |
| properties. |
| .sp |
| See also the \fBRUNTIME_OUTPUT_NAME_<CONFIG>\fP target property. |
| .SS RUNTIME_OUTPUT_NAME_<CONFIG> |
| .sp |
| Per\-configuration output name for |
| RUNTIME target files. |
| .sp |
| This is the configuration\-specific version of the |
| \fBRUNTIME_OUTPUT_NAME\fP target property. |
| .SS SKIP_BUILD_RPATH |
| .sp |
| Should rpaths be used for the build tree. |
| .sp |
| \fBSKIP_BUILD_RPATH\fP is a boolean specifying whether to skip automatic |
| generation of an rpath allowing the target to run from the build tree. |
| This property is initialized by the value of the variable |
| \fBCMAKE_SKIP_BUILD_RPATH\fP if it is set when a target is created. |
| .SS SOURCE_DIR |
| .sp |
| New in version 3.4. |
| |
| .sp |
| This read\-only property reports the value of the |
| \fBCMAKE_CURRENT_SOURCE_DIR\fP variable in the directory in which |
| the target was defined. |
| .SS SOURCES |
| .sp |
| This specifies the list of paths to source files for the target. |
| The following commands all set or add to the \fBSOURCES\fP target property |
| and are the usual way to manipulate it: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBadd_executable()\fP |
| .IP \(bu 2 |
| \fBadd_library()\fP |
| .IP \(bu 2 |
| \fBadd_custom_target()\fP |
| .IP \(bu 2 |
| \fBtarget_sources()\fP |
| .UNINDENT |
| .sp |
| Contents of \fBSOURCES\fP may use |
| \fBgenerator expressions\fP\&. |
| If a path starts with a generator expression, it is expected to |
| evaluate to an absolute path. Not doing so is considered undefined behavior. |
| .sp |
| Paths that are for files generated by the build will be treated |
| as relative to the build directory of the target, if the path is not |
| already specified as an absolute path. Note that whether a file is seen as |
| generated may be affected by policy \fBCMP0118\fP\&. |
| .sp |
| If a path does not start with a generator expression, is not an |
| absolute path and is not a generated file, it will be treated as relative to |
| the location selected by the first of the following that matches: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| If a file by the specified path exists relative to the target\(aqs source |
| directory, use that file. |
| .IP \(bu 2 |
| If policy \fBCMP0115\fP is not set to \fBNEW\fP, try appending each |
| known source file extension to the path and check if that exists |
| relative to the target\(aqs source directory. |
| .IP \(bu 2 |
| Repeat the above two steps, this time relative to the target\(aqs binary |
| directory instead. |
| .UNINDENT |
| .sp |
| Note that the above decisions are made at generation time, not build time. |
| .sp |
| See the \fBcmake\-buildsystem(7)\fP manual for more on defining |
| buildsystem properties. |
| .SS SOVERSION |
| .sp |
| What version number is this target. |
| .sp |
| For shared libraries \fBVERSION\fP and \fBSOVERSION\fP can be used to |
| specify the build version and API version respectively. When building or |
| installing appropriate symlinks are created if the platform supports |
| symlinks and the linker supports so\-names. If only one of both is |
| specified the missing is assumed to have the same version number. |
| \fBSOVERSION\fP is ignored if \fBNO_SONAME\fP property is set. |
| .SS Windows Versions |
| .sp |
| For shared libraries and executables on Windows the \fBVERSION\fP |
| attribute is parsed to extract a \fB<major>.<minor>\fP version number. |
| These numbers are used as the image version of the binary. |
| .SS Mach\-O Versions |
| .sp |
| For shared libraries and executables on Mach\-O systems (e.g. macOS, iOS), |
| the \fBSOVERSION\fP property corresponds to the \fIcompatibility version\fP and |
| \fBVERSION\fP corresponds to the \fIcurrent version\fP (unless Mach\-O |
| specific overrides are provided, as discussed below). |
| See the \fBFRAMEWORK\fP target property for an example. |
| .sp |
| For shared libraries, the \fBMACHO_COMPATIBILITY_VERSION\fP and |
| \fBMACHO_CURRENT_VERSION\fP properties can be used to |
| override the \fIcompatibility version\fP and \fIcurrent version\fP respectively. |
| Note that \fBSOVERSION\fP will still be used to form the \fBinstall_name\fP |
| and both \fBSOVERSION\fP and \fBVERSION\fP may also affect the file |
| and symlink names. |
| .sp |
| Versions of Mach\-O binaries may be checked with the \fBotool \-L <binary>\fP |
| command. |
| .SS STATIC_LIBRARY_FLAGS |
| .sp |
| Archiver (or MSVC librarian) flags for a static library target. |
| Targets that are shared libraries, modules, or executables need to use |
| the \fBLINK_OPTIONS\fP or \fBLINK_FLAGS\fP target properties. |
| .sp |
| The \fBSTATIC_LIBRARY_FLAGS\fP property, managed as a string, can be used to add |
| extra flags to the link step of a static library target. |
| \fBSTATIC_LIBRARY_FLAGS_<CONFIG>\fP will add to the configuration |
| \fB<CONFIG>\fP, for example, \fBDEBUG\fP, \fBRELEASE\fP, \fBMINSIZEREL\fP, |
| \fBRELWITHDEBINFO\fP, ... |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This property has been superseded by \fBSTATIC_LIBRARY_OPTIONS\fP |
| property. |
| .UNINDENT |
| .UNINDENT |
| .SS STATIC_LIBRARY_FLAGS_<CONFIG> |
| .sp |
| Per\-configuration archiver (or MSVC librarian) flags for a static library |
| target. |
| .sp |
| This is the configuration\-specific version of \fBSTATIC_LIBRARY_FLAGS\fP\&. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This property has been superseded by \fBSTATIC_LIBRARY_OPTIONS\fP |
| property. |
| .UNINDENT |
| .UNINDENT |
| .SS STATIC_LIBRARY_OPTIONS |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Archiver (or MSVC librarian) flags for a static library target. |
| Targets that are shared libraries, modules, or executables need to use |
| the \fBLINK_OPTIONS\fP target property. |
| .sp |
| This property holds a semicolon\-separated list of options |
| specified so far for its target. Use \fBset_target_properties()\fP or |
| \fBset_property()\fP commands to set its content. |
| .sp |
| Contents of \fBSTATIC_LIBRARY_OPTIONS\fP may use "generator expressions" with the |
| syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP manual |
| for available expressions. See the \fBcmake\-buildsystem(7)\fP manual |
| for more on defining buildsystem properties. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This property must be used in preference to \fBSTATIC_LIBRARY_FLAGS\fP |
| property. |
| .UNINDENT |
| .UNINDENT |
| .SS Option De\-duplication |
| .sp |
| The final set of options used for a target is constructed by |
| accumulating options from the current target and the usage requirements of |
| its dependencies. The set of options is de\-duplicated to avoid repetition. |
| .sp |
| New in version 3.12: While beneficial for individual options, the de\-duplication step can break |
| up option groups. For example, \fB\-option A \-option B\fP becomes |
| \fB\-option A B\fP\&. One may specify a group of options using shell\-like |
| quoting along with a \fBSHELL:\fP prefix. The \fBSHELL:\fP prefix is dropped, |
| and the rest of the option string is parsed using the |
| \fBseparate_arguments()\fP \fBUNIX_COMMAND\fP mode. For example, |
| \fB"SHELL:\-option A" "SHELL:\-option B"\fP becomes \fB\-option A \-option B\fP\&. |
| |
| .SS SUFFIX |
| .sp |
| What comes after the target name. |
| .sp |
| A target property that can be set to override the suffix (such as |
| \fB\&.so\fP or \fB\&.exe\fP) on the name of a library, module or executable. |
| .SS Swift_DEPENDENCIES_FILE |
| .sp |
| New in version 3.15. |
| |
| .sp |
| This property sets the path for the Swift dependency file (swiftdep) for the |
| target. If one is not specified, it will default to \fB<TARGET>.swiftdeps\fP\&. |
| .SS Swift_LANGUAGE_VERSION |
| .sp |
| New in version 3.16. |
| |
| .sp |
| This property sets the language version for the Swift sources in the target. If |
| one is not specified, it will default to \fB<CMAKE_Swift_LANGUAGE_VERSION>\fP if |
| specified, otherwise it is the latest version supported by the compiler. |
| .SS Swift_MODULE_DIRECTORY |
| .sp |
| New in version 3.15. |
| |
| .sp |
| Specify output directory for Swift modules provided by the target. |
| .sp |
| If the target contains Swift source files, this specifies the directory in which |
| the modules will be placed. When this property is not set, the modules will be |
| placed in the build directory corresponding to the target\(aqs source directory. |
| If the variable \fBCMAKE_Swift_MODULE_DIRECTORY\fP is set when a target is |
| created its value is used to initialize this property. |
| .SS Swift_MODULE_NAME |
| .sp |
| New in version 3.15. |
| |
| .sp |
| This property specifies the name of the Swift module. It is defaulted to the |
| name of the target. |
| .SS TYPE |
| .sp |
| The type of the target. |
| .sp |
| This read\-only property can be used to test the type of the given |
| target. It will be one of \fBSTATIC_LIBRARY\fP, \fBMODULE_LIBRARY\fP, |
| \fBSHARED_LIBRARY\fP, \fBOBJECT_LIBRARY\fP, \fBINTERFACE_LIBRARY\fP, \fBEXECUTABLE\fP |
| or one of the internal target types. |
| .SS UNITY_BUILD |
| .sp |
| New in version 3.16. |
| |
| .sp |
| When this property is set to true, the target source files will be combined |
| into batches for faster compilation. This is done by creating a (set of) |
| unity sources which \fB#include\fP the original sources, then compiling these |
| unity sources instead of the originals. This is known as a \fIUnity\fP or \fIJumbo\fP |
| build. |
| .sp |
| CMake provides different algorithms for selecting which sources are grouped |
| together into a \fIbucket\fP\&. Algorithm selection is decided by the |
| \fBUNITY_BUILD_MODE\fP target property, which has the following acceptable |
| values: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBBATCH\fP |
| When in this mode CMake determines which files are grouped together. |
| The \fBUNITY_BUILD_BATCH_SIZE\fP property controls the upper limit on |
| how many sources can be combined per unity source file. |
| .IP \(bu 2 |
| \fBGROUP\fP |
| When in this mode each target explicitly specifies how to group |
| source files. Each source file that has the same |
| \fBUNITY_GROUP\fP value will be grouped together. Any sources |
| that don\(aqt have this property will be compiled individually. The |
| \fBUNITY_BUILD_BATCH_SIZE\fP property is ignored when using |
| this mode. |
| .UNINDENT |
| .sp |
| If no explicit \fBUNITY_BUILD_MODE\fP has been specified, CMake will |
| default to \fBBATCH\fP\&. |
| .sp |
| Unity builds are not currently supported for all languages. CMake version |
| 3.23.1 supports combining \fBC\fP and \fBCXX\fP source files. For targets that |
| mix source files from more than one language, CMake will separate the languages |
| such that each generated unity source file only contains sources for a single |
| language. |
| .sp |
| This property is initialized by the value of the \fBCMAKE_UNITY_BUILD\fP |
| variable when a target is created. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Projects should not directly set the \fBUNITY_BUILD\fP property or its |
| associated \fBCMAKE_UNITY_BUILD\fP variable to true. Depending |
| on the capabilities of the build machine and compiler used, it might or |
| might not be appropriate to enable unity builds. Therefore, this feature |
| should be under developer control, which would normally be through the |
| developer choosing whether or not to set the \fBCMAKE_UNITY_BUILD\fP |
| variable on the \fBcmake(1)\fP command line or some other equivalent |
| method. However, it IS recommended to set the \fBUNITY_BUILD\fP target |
| property to false if it is known that enabling unity builds for the |
| target can lead to problems. |
| .UNINDENT |
| .UNINDENT |
| .SS ODR (One definition rule) errors |
| .sp |
| When multiple source files are included into one source file, as is done |
| for unity builds, it can potentially lead to ODR errors. CMake provides |
| a number of measures to help address such problems: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| Any source file that has a non\-empty \fBCOMPILE_OPTIONS\fP, |
| \fBCOMPILE_DEFINITIONS\fP, \fBCOMPILE_FLAGS\fP, or |
| \fBINCLUDE_DIRECTORIES\fP source property will not be combined |
| into a unity source. |
| .IP \(bu 2 |
| Projects can prevent an individual source file from being combined into |
| a unity source by setting its \fBSKIP_UNITY_BUILD_INCLUSION\fP |
| source property to true. This can be a more effective way to prevent |
| problems with specific files than disabling unity builds for an entire |
| target. |
| .IP \(bu 2 |
| Projects can set \fBUNITY_BUILD_UNIQUE_ID\fP to cause a valid |
| C\-identifier to be generated which is unique per file in a unity |
| build. This can be used to avoid problems with anonymous namespaces |
| in unity builds. |
| .IP \(bu 2 |
| The \fBUNITY_BUILD_CODE_BEFORE_INCLUDE\fP and |
| \fBUNITY_BUILD_CODE_AFTER_INCLUDE\fP target properties can be used |
| to inject code into the unity source files before and after every |
| \fB#include\fP statement. |
| .IP \(bu 2 |
| The order of source files added to the target via commands like |
| \fBadd_library()\fP, \fBadd_executable()\fP or |
| \fBtarget_sources()\fP will be preserved in the generated unity source |
| files. This can be used to manually enforce a specific grouping based on |
| the \fBUNITY_BUILD_BATCH_SIZE\fP target property. |
| .UNINDENT |
| .SS UNITY_BUILD_BATCH_SIZE |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Specifies the maximum number of source files that can be combined into any one |
| unity source file when unity builds are enabled by the \fBUNITY_BUILD\fP |
| target property. The original source files will be distributed across as many |
| unity source files as necessary to honor this limit. |
| .sp |
| The initial value for this property is taken from the |
| \fBCMAKE_UNITY_BUILD_BATCH_SIZE\fP variable when the target is created. |
| If that variable has not been set, the initial value will be 8. |
| .sp |
| The batch size needs to be selected carefully. If set too high, the size of |
| the combined source files could result in the compiler using excessive memory |
| or hitting other similar limits. In extreme cases, this can even result in |
| build failure. On the other hand, if the batch size is too low, there will be |
| little gain in build performance. |
| .sp |
| Although strongly discouraged, the batch size may be set to a value of 0 to |
| combine all the sources for the target into a single unity file, regardless of |
| how many sources are involved. This runs the risk of creating an excessively |
| large unity source file and negatively impacting the build performance, so |
| a value of 0 is not generally recommended. |
| .SS UNITY_BUILD_CODE_AFTER_INCLUDE |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Code snippet which is included verbatim by the \fBUNITY_BUILD\fP |
| feature just after every \fB#include\fP statement in the generated unity |
| source files. For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(after [[ |
| #if defined(NOMINMAX) |
| #undef NOMINMAX |
| #endif |
| ]]) |
| set_target_properties(myTarget PROPERTIES |
| UNITY_BUILD_CODE_AFTER_INCLUDE "${after}" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| See also \fBUNITY_BUILD_CODE_BEFORE_INCLUDE\fP\&. |
| .SS UNITY_BUILD_CODE_BEFORE_INCLUDE |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Code snippet which is included verbatim by the \fBUNITY_BUILD\fP |
| feature just before every \fB#include\fP statement in the generated unity |
| source files. For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(before [[ |
| #if !defined(NOMINMAX) |
| #define NOMINMAX |
| #endif |
| ]]) |
| set_target_properties(myTarget PROPERTIES |
| UNITY_BUILD_CODE_BEFORE_INCLUDE "${before}" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| See also \fBUNITY_BUILD_CODE_AFTER_INCLUDE\fP\&. |
| .SS UNITY_BUILD_MODE |
| .sp |
| New in version 3.18. |
| |
| .sp |
| CMake provides different algorithms for selecting which sources are grouped |
| together into a \fIbucket\fP\&. Selection is decided by this property, |
| which has the following acceptable values: |
| .INDENT 0.0 |
| .TP |
| .B \fBBATCH\fP |
| When in this mode CMake determines which files are grouped together. |
| The \fBUNITY_BUILD_BATCH_SIZE\fP property controls the upper limit on |
| how many sources can be combined per unity source file. |
| .sp |
| Example usage: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(example_library |
| source1.cxx |
| source2.cxx |
| source3.cxx |
| source4.cxx) |
| |
| set_target_properties(example_library PROPERTIES |
| UNITY_BUILD_MODE BATCH |
| UNITY_BUILD_BATCH_SIZE 2 |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBGROUP\fP |
| When in this mode each target explicitly specifies how to group |
| source files. Each source file that has the same |
| \fBUNITY_GROUP\fP value will be grouped together. Any sources |
| that don\(aqt have this property will be compiled individually. The |
| \fBUNITY_BUILD_BATCH_SIZE\fP property is ignored when using |
| this mode. |
| .sp |
| Example usage: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(example_library |
| source1.cxx |
| source2.cxx |
| source3.cxx |
| source4.cxx) |
| |
| set_target_properties(example_library PROPERTIES |
| UNITY_BUILD_MODE GROUP |
| ) |
| |
| set_source_files_properties(source1.cxx source2.cxx source3.cxx |
| PROPERTIES UNITY_GROUP "bucket1" |
| ) |
| set_source_files_properties(source4.cxx |
| PROPERTIES UNITY_GROUP "bucket2" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If no explicit \fI\%UNITY_BUILD_MODE\fP has been specified, CMake will |
| default to \fBBATCH\fP\&. |
| .SS UNITY_BUILD_UNIQUE_ID |
| .sp |
| New in version 3.20. |
| |
| .sp |
| The name of a valid C\-identifier which is set to a unique per\-file |
| value during unity builds. |
| .sp |
| When this property is populated and when \fBUNITY_BUILD\fP |
| is true, the property value is used to define a compiler definition |
| of the specified name. The value of the defined symbol is unspecified, |
| but it is unique per file path. |
| .sp |
| Given: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_target_properties(myTarget PROPERTIES |
| UNITY_BUILD "ON" |
| UNITY_BUILD_UNIQUE_ID "MY_UNITY_ID" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| the \fBMY_UNITY_ID\fP symbol is defined to a unique per\-file value. |
| .sp |
| One known use case for this identifier is to disambiguate the |
| variables in an anonymous namespace in a limited scope. |
| Anonymous namespaces present a problem for unity builds because |
| they are used to ensure that certain variables and declarations |
| are scoped to a translation unit which is approximated by a |
| single source file. When source files are combined in a unity |
| build file, those variables in different files are combined in |
| a single translation unit and the names clash. This property can |
| be used to avoid that with code like the following: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| // Needed for when unity builds are disabled |
| #ifndef MY_UNITY_ID |
| #define MY_UNITY_ID |
| #endif |
| |
| namespace { namespace MY_UNITY_ID { |
| // The name \(aqi\(aq clashes (or could clash) with other |
| // variables in other anonymous namespaces |
| int i = 42; |
| }} |
| |
| int use_var() |
| { |
| return MY_UNITY_ID::i; |
| } |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The pseudonymous namespace is used within a truly anonymous namespace. |
| On many platforms, this maintains the invariant that the symbols within |
| do not get external linkage when performing a unity build. |
| .SS VERSION |
| .sp |
| What version number is this target. |
| .sp |
| For shared libraries \fBVERSION\fP and \fBSOVERSION\fP can be used |
| to specify the build version and API version respectively. When building or |
| installing appropriate symlinks are created if the platform supports |
| symlinks and the linker supports so\-names. If only one of both is |
| specified the missing is assumed to have the same version number. For |
| executables \fBVERSION\fP can be used to specify the build version. When |
| building or installing appropriate symlinks are created if the |
| platform supports symlinks. |
| .SS Windows Versions |
| .sp |
| For shared libraries and executables on Windows the \fBVERSION\fP |
| attribute is parsed to extract a \fB<major>.<minor>\fP version number. |
| These numbers are used as the image version of the binary. |
| .SS Mach\-O Versions |
| .sp |
| For shared libraries and executables on Mach\-O systems (e.g. macOS, iOS), |
| the \fBSOVERSION\fP property corresponds to the \fIcompatibility version\fP |
| and \fBVERSION\fP corresponds to the \fIcurrent version\fP (unless Mach\-O specific |
| overrides are provided, as discussed below). |
| See the \fBFRAMEWORK\fP target property for an example. |
| .sp |
| For shared libraries, the \fBMACHO_COMPATIBILITY_VERSION\fP and |
| \fBMACHO_CURRENT_VERSION\fP properties can be used to |
| override the \fIcompatibility version\fP and \fIcurrent version\fP respectively. |
| Note that \fBSOVERSION\fP will still be used to form the |
| \fBinstall_name\fP and both \fBSOVERSION\fP and \fBVERSION\fP may also |
| affect the file and symlink names. |
| .sp |
| Versions of Mach\-O binaries may be checked with the \fBotool \-L <binary>\fP |
| command. |
| .SS VISIBILITY_INLINES_HIDDEN |
| .sp |
| Whether to add a compile flag to hide symbols of inline functions |
| .sp |
| The \fBVISIBILITY_INLINES_HIDDEN\fP property determines whether a flag for |
| hiding symbols for inline functions, such as \fB\-fvisibility\-inlines\-hidden\fP, |
| should be used when invoking the compiler. This property affects compilation |
| in sources of all types of targets (subject to policy \fBCMP0063\fP). |
| .sp |
| This property is initialized by |
| the value of the \fBCMAKE_VISIBILITY_INLINES_HIDDEN\fP variable if it |
| is set when a target is created. |
| .SS VS_CONFIGURATION_TYPE |
| .sp |
| New in version 3.6. |
| |
| .sp |
| Visual Studio project configuration type. |
| .sp |
| Sets the \fBConfigurationType\fP attribute for a generated Visual Studio project. |
| The property value may use |
| \fBgenerator expressions\fP\&. |
| If this property is set, it overrides the default setting that is based on the |
| target type (e.g. \fBStaticLibrary\fP, \fBApplication\fP, ...). |
| .sp |
| Supported on Visual Studio Generators for VS 2010 and higher. |
| .SS VS_DEBUGGER_COMMAND |
| .sp |
| New in version 3.12. |
| |
| .sp |
| Sets the local debugger command for Visual Studio C++ targets. |
| The property value may use |
| \fBgenerator expressions\fP\&. |
| This is defined in \fB<LocalDebuggerCommand>\fP in the Visual Studio |
| project file. |
| .sp |
| This property only works for Visual Studio 2010 and above; |
| it is ignored on other generators. |
| .SS VS_DEBUGGER_COMMAND_ARGUMENTS |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Sets the local debugger command line arguments for Visual Studio C++ targets. |
| The property value may use |
| \fBgenerator expressions\fP\&. |
| This is defined in \fB<LocalDebuggerCommandArguments>\fP in the Visual Studio |
| project file. |
| .sp |
| This property only works for Visual Studio 2010 and above; |
| it is ignored on other generators. |
| .SS VS_DEBUGGER_ENVIRONMENT |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Sets the local debugger environment for Visual Studio C++ targets. |
| The property value may use |
| \fBgenerator expressions\fP\&. |
| This is defined in \fB<LocalDebuggerEnvironment>\fP in the Visual Studio |
| project file. |
| .sp |
| This property only works for Visual Studio 2010 and above; |
| it is ignored on other generators. |
| .SS VS_DEBUGGER_WORKING_DIRECTORY |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Sets the local debugger working directory for Visual Studio C++ targets. |
| The property value may use |
| \fBgenerator expressions\fP\&. |
| This is defined in \fB<LocalDebuggerWorkingDirectory>\fP in the Visual Studio |
| project file. |
| .sp |
| This property only works for Visual Studio 2010 and above; |
| it is ignored on other generators. |
| .SS VS_DESKTOP_EXTENSIONS_VERSION |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Visual Studio Windows 10 Desktop Extensions Version |
| .sp |
| Specifies the version of the Desktop Extensions that should be included in the |
| target. For example \fB10.0.10240.0\fP\&. If the value is not specified, the Desktop |
| Extensions will not be included. To use the same version of the extensions as |
| the Windows 10 SDK that is being used, you can use the |
| \fBCMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION\fP variable. |
| .SS VS_DOTNET_DOCUMENTATION_FILE |
| .sp |
| New in version 3.17. |
| |
| .sp |
| Visual Studio managed project .NET documentation output |
| .sp |
| Sets the target XML documentation file output. |
| .SS VS_DOTNET_REFERENCE_<refname> |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Visual Studio managed project .NET reference with name \fB<refname>\fP |
| and hint path. |
| .sp |
| Adds one .NET reference to generated Visual Studio project. The |
| reference will have the name \fB<refname>\fP and will point to the |
| assembly given as value of the property. |
| .sp |
| See also \fBVS_DOTNET_REFERENCES\fP and |
| \fBVS_DOTNET_REFERENCES_COPY_LOCAL\fP |
| .SS VS_DOTNET_REFERENCEPROP_<refname>_TAG_<tagname> |
| .sp |
| New in version 3.10. |
| |
| .sp |
| Defines an XML property \fB<tagname>\fP for a .NET reference |
| \fB<refname>\fP\&. |
| .sp |
| Reference properties can be set for .NET references which are |
| defined by the target properties \fBVS_DOTNET_REFERENCES\fP, |
| \fBVS_DOTNET_REFERENCE_<refname>\fP |
| and also for project references to other C# targets which are |
| established by \fBtarget_link_libraries()\fP\&. |
| .sp |
| This property is only applicable to C# targets and Visual Studio |
| generators 2010 and later. |
| .SS VS_DOTNET_REFERENCES |
| .sp |
| Visual Studio managed project .NET references |
| .sp |
| Adds one or more semicolon\-delimited .NET references to a generated |
| Visual Studio project. For example, "System;System.Windows.Forms". |
| .SS VS_DOTNET_REFERENCES_COPY_LOCAL |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Sets the \fBCopy Local\fP property for all .NET hint references in the target |
| .sp |
| Boolean property to enable/disable copying of .NET hint references to |
| output directory. The default is \fBON\fP\&. |
| .SS VS_DOTNET_TARGET_FRAMEWORK_VERSION |
| .sp |
| Specify the .NET target framework version. |
| .sp |
| Used to specify the .NET target framework version for C++/CLI. For |
| example, "v4.5". |
| .sp |
| This property is deprecated and should not be used anymore. Use |
| \fBDOTNET_TARGET_FRAMEWORK\fP or |
| \fBDOTNET_TARGET_FRAMEWORK_VERSION\fP instead. |
| .SS VS_DPI_AWARE |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Set the Manifest Tool \-> Input and Output \-> DPI Awareness in the Visual Studio |
| target project properties. |
| .sp |
| Valid values are \fBPerMonitor\fP, \fBON\fP, or \fBOFF\fP\&. |
| .sp |
| For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_executable(myproject myproject.cpp) |
| set_property(TARGET myproject PROPERTY VS_DPI_AWARE "PerMonitor") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS VS_GLOBAL_KEYWORD |
| .sp |
| Visual Studio project keyword for VS 10 (2010) and newer. |
| .sp |
| Sets the "keyword" attribute for a generated Visual Studio project. |
| Defaults to "Win32Proj". You may wish to override this value with |
| "ManagedCProj", for example, in a Visual Studio managed C++ unit test |
| project. |
| .sp |
| Use the \fBVS_KEYWORD\fP target property to set the |
| keyword for Visual Studio 9 (2008) and older. |
| .SS VS_GLOBAL_PROJECT_TYPES |
| .sp |
| Visual Studio project type(s). |
| .sp |
| Can be set to one or more UUIDs recognized by Visual Studio to |
| indicate the type of project. This value is copied verbatim into the |
| generated project file. Example for a managed C++ unit testing |
| project: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| {3AC096D0\-A1C2\-E12C\-1390\-A8335801FDAB};{8BC9CEB8\-8B4A\-11D0\-8D11\-00A0C91BC942} |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| UUIDs are semicolon\-delimited. |
| .SS VS_GLOBAL_ROOTNAMESPACE |
| .sp |
| Visual Studio project root namespace. |
| .sp |
| Sets the "RootNamespace" attribute for a generated Visual Studio |
| project. The attribute will be generated only if this is set. |
| .SS VS_GLOBAL_<variable> |
| .sp |
| Visual Studio project\-specific global variable. |
| .sp |
| Tell the Visual Studio generator to set the global variable |
| \(aq<variable>\(aq to a given value in the generated Visual Studio project. |
| Ignored on other generators. Qt integration works better if |
| VS_GLOBAL_QtVersion is set to the version FindQt4.cmake found. For |
| example, "4.7.3" |
| .SS VS_IOT_EXTENSIONS_VERSION |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Visual Studio Windows 10 IoT Extensions Version |
| .sp |
| Specifies the version of the IoT Extensions that should be included in the |
| target. For example \fB10.0.10240.0\fP\&. If the value is not specified, the IoT |
| Extensions will not be included. To use the same version of the extensions as |
| the Windows 10 SDK that is being used, you can use the |
| \fBCMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION\fP variable. |
| .SS VS_IOT_STARTUP_TASK |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Visual Studio Windows 10 IoT Continuous Background Task |
| .sp |
| Specifies that the target should be compiled as a Continuous Background Task library. |
| .SS VS_JUST_MY_CODE_DEBUGGING |
| .sp |
| New in version 3.15. |
| |
| .sp |
| Enable Just My Code with Visual Studio debugger. |
| .sp |
| Supported on Visual Studio Generators for VS 2010 and higher, |
| Makefile Generators and the \fBNinja\fP generators. |
| .sp |
| This property is initialized by the \fBCMAKE_VS_JUST_MY_CODE_DEBUGGING\fP |
| variable if it is set when a target is created. |
| .SS VS_KEYWORD |
| .sp |
| Visual Studio project keyword for VS 9 (2008) and older. |
| .sp |
| Can be set to change the visual studio keyword, for example Qt |
| integration works better if this is set to Qt4VSv1.0. |
| .sp |
| Use the \fBVS_GLOBAL_KEYWORD\fP target property to set the |
| keyword for Visual Studio 10 (2010) and newer. |
| .SS VS_MOBILE_EXTENSIONS_VERSION |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Visual Studio Windows 10 Mobile Extensions Version |
| .sp |
| Specifies the version of the Mobile Extensions that should be included in the |
| target. For example \fB10.0.10240.0\fP\&. If the value is not specified, the Mobile |
| Extensions will not be included. To use the same version of the extensions as |
| the Windows 10 SDK that is being used, you can use the |
| \fBCMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION\fP variable. |
| .SS VS_NO_SOLUTION_DEPLOY |
| .sp |
| New in version 3.15. |
| |
| .sp |
| Specify that the target should not be marked for deployment to a Windows CE |
| or Windows Phone device in the generated Visual Studio solution. |
| .sp |
| Be default, all EXE and shared library (DLL) targets are marked to deploy to |
| the target device in the generated Visual Studio solution. |
| .sp |
| Generator expressions are supported. |
| .sp |
| There are reasons one might want to exclude a target / generated project from |
| deployment: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| The library or executable may not be necessary in the primary deploy/debug |
| scenario, and excluding from deployment saves time in the |
| develop/download/debug cycle. |
| .IP \(bu 2 |
| There may be insufficient space on the target device to accommodate all of |
| the build products. |
| .IP \(bu 2 |
| Visual Studio 2013 requires a target device IP address be entered for each |
| target marked for deployment. For large numbers of targets, this can be |
| tedious. |
| NOTE: Visual Studio \fIwill\fP deploy all project dependencies of a project |
| tagged for deployment to the IP address configured for that project even |
| if those dependencies are not tagged for deployment. |
| .UNINDENT |
| .SS Example 1 |
| .sp |
| This shows setting the variable for the target foo. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(foo SHARED foo.cpp) |
| set_property(TARGET foo PROPERTY VS_NO_SOLUTION_DEPLOY ON) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Example 2 |
| .sp |
| This shows setting the variable for the Release configuration only. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(foo SHARED foo.cpp) |
| set_property(TARGET foo PROPERTY VS_NO_SOLUTION_DEPLOY "$<CONFIG:Release>") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS VS_PACKAGE_REFERENCES |
| .sp |
| New in version 3.15. |
| |
| .sp |
| Visual Studio package references for nuget. |
| .sp |
| Adds one or more semicolon\-delimited package references to a generated |
| Visual Studio project. The version of the package will be |
| underscore delimited. For example, \fBboost_1.7.0;nunit_3.12.*\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET ${TARGET_NAME} PROPERTY |
| VS_PACKAGE_REFERENCES "boost_1.7.0") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS VS_PLATFORM_TOOLSET |
| .sp |
| New in version 3.18. |
| |
| .sp |
| Overrides the platform toolset used to build a target. |
| .sp |
| Only supported when the compiler used by the given toolset is the |
| same as the compiler used to build the whole source tree. |
| .sp |
| This is especially useful to create driver projects with the toolsets |
| "WindowsUserModeDriver10.0" or "WindowsKernelModeDriver10.0". |
| .SS VS_PROJECT_IMPORT |
| .sp |
| New in version 3.15. |
| |
| .sp |
| Visual Studio managed project imports |
| .sp |
| Adds to a generated Visual Studio project one or more semicolon\-delimited paths |
| to .props files needed when building projects from some NuGet packages. |
| For example, \fBmy_packages_path/MyPackage.1.0.0/build/MyPackage.props\fP\&. |
| .SS VS_SCC_AUXPATH |
| .sp |
| Visual Studio Source Code Control Aux Path. |
| .sp |
| Can be set to change the visual studio source code control auxpath |
| property. |
| .SS VS_SCC_LOCALPATH |
| .sp |
| Visual Studio Source Code Control Local Path. |
| .sp |
| Can be set to change the visual studio source code control local path |
| property. |
| .SS VS_SCC_PROJECTNAME |
| .sp |
| Visual Studio Source Code Control Project. |
| .sp |
| Can be set to change the visual studio source code control project |
| name property. |
| .SS VS_SCC_PROVIDER |
| .sp |
| Visual Studio Source Code Control Provider. |
| .sp |
| Can be set to change the visual studio source code control provider |
| property. |
| .SS VS_SDK_REFERENCES |
| .sp |
| New in version 3.7. |
| |
| .sp |
| Visual Studio project SDK references. |
| Specify a semicolon\-separated list of SDK references |
| to be added to a generated Visual Studio project, e.g. |
| \fBMicrosoft.AdMediatorWindows81, Version=1.0\fP\&. |
| .SS VS_SOLUTION_DEPLOY |
| .sp |
| New in version 3.18. |
| |
| .sp |
| Specify that the target should be marked for deployment when not targeting |
| Windows CE, Windows Phone or a Windows Store application. |
| .sp |
| If the target platform doesn\(aqt support deployment, this property won\(aqt have |
| any effect. |
| .sp |
| \fBGenerator expressions\fP are supported. |
| .SS Examples |
| .sp |
| Always deploy target \fBfoo\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_executable(foo SHARED foo.cpp) |
| set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY ON) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Deploy target \fBfoo\fP for all configurations except \fBRelease\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_executable(foo SHARED foo.cpp) |
| set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY "$<NOT:$<CONFIG:Release>>") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS VS_SOURCE_SETTINGS_<tool> |
| .sp |
| New in version 3.18. |
| |
| .sp |
| Set any item metadata on all non\-built files that use <tool>. |
| .sp |
| Takes a list of \fBKey=Value\fP pairs. Tells the Visual Studio generator |
| to set \fBKey\fP to \fBValue\fP as item metadata on all non\-built files |
| that use \fB<tool>\fP\&. |
| .sp |
| For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TARGET main PROPERTY VS_SOURCE_SETTINGS_FXCompile "Key=Value" "Key2=Value2") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| will set \fBKey\fP to \fBValue\fP and \fBKey2\fP to \fBValue2\fP for all |
| non\-built files that use \fBFXCompile\fP\&. |
| .sp |
| \fBGenerator expressions\fP are supported. |
| .SS VS_USER_PROPS |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Sets the user props file to be included in the visual studio |
| C++ project file. The standard path is |
| \fB$(UserRootDir)\e\eMicrosoft.Cpp.$(Platform).user.props\fP, which is |
| in most cases the same as |
| \fB%LOCALAPPDATA%\e\eMicrosoft\e\eMSBuild\e\ev4.0\e\eMicrosoft.Cpp.Win32.user.props\fP |
| or \fB%LOCALAPPDATA%\e\eMicrosoft\e\eMSBuild\e\ev4.0\e\eMicrosoft.Cpp.x64.user.props\fP\&. |
| .sp |
| The \fB*.user.props\fP files can be used for Visual Studio wide |
| configuration which is independent from cmake. |
| .SS VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Visual Studio Windows Target Platform Minimum Version |
| .sp |
| For Windows 10. Specifies the minimum version of the OS that is being |
| targeted. For example \fB10.0.10240.0\fP\&. If the value is not specified, the |
| value of \fBCMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION\fP will be used on |
| WindowsStore projects otherwise the target platform minimum version will not |
| be specified for the project. |
| .SS VS_WINRT_COMPONENT |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Mark a target as a Windows Runtime component for the Visual Studio generator. |
| Compile the target with \fBC++/CX\fP language extensions for Windows Runtime. |
| For \fBSHARED\fP and \fBMODULE\fP libraries, this also defines the |
| \fB_WINRT_DLL\fP preprocessor macro. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Currently this is implemented only by Visual Studio generators. |
| Support may be added to other generators in the future. |
| .UNINDENT |
| .UNINDENT |
| .SS VS_WINRT_EXTENSIONS |
| .sp |
| Deprecated. Use \fBVS_WINRT_COMPONENT\fP instead. |
| This property was an experimental partial implementation of that one. |
| .SS VS_WINRT_REFERENCES |
| .sp |
| Visual Studio project Windows Runtime Metadata references |
| .sp |
| Adds one or more semicolon\-delimited WinRT references to a generated |
| Visual Studio project. For example, "Windows;Windows.UI.Core". |
| .SS WIN32_EXECUTABLE |
| .sp |
| Build an executable with a WinMain entry point on windows. |
| .sp |
| When this property is set to true the executable when linked on |
| Windows will be created with a WinMain() entry point instead of just |
| main(). This makes it a GUI executable instead of a console application. |
| See the \fBCMAKE_MFC_FLAG\fP variable documentation to |
| configure use of the Microsoft Foundation Classes (MFC) for WinMain |
| executables. This property is initialized by the value of the |
| \fBCMAKE_WIN32_EXECUTABLE\fP variable if it is set when |
| a target is created. |
| .sp |
| This property supports |
| \fBgenerator expressions\fP, except if the |
| target is managed (contains C# code.) |
| .SS WINDOWS_EXPORT_ALL_SYMBOLS |
| .sp |
| New in version 3.4. |
| |
| .sp |
| This property is implemented only for MS\-compatible tools on Windows. |
| .sp |
| Enable this boolean property to automatically create a module definition |
| (\fB\&.def\fP) file with all global symbols found in the input \fB\&.obj\fP files |
| for a \fBSHARED\fP library (or executable with \fBENABLE_EXPORTS\fP) |
| on Windows. The module definition file will be passed to the linker |
| causing all symbols to be exported from the \fB\&.dll\fP\&. |
| For global \fIdata\fP symbols, \fB__declspec(dllimport)\fP must still be used when |
| compiling against the code in the \fB\&.dll\fP\&. All other function symbols will |
| be automatically exported and imported by callers. This simplifies porting |
| projects to Windows by reducing the need for explicit \fBdllexport\fP markup, |
| even in \fBC++\fP classes. |
| .sp |
| When this property is enabled, zero or more \fB\&.def\fP files may also be |
| specified as source files of the target. The exports named by these files |
| will be merged with those detected from the object files to generate a |
| single module definition file to be passed to the linker. This can be |
| used to export symbols from a \fB\&.dll\fP that are not in any of its object |
| files but are added by the linker from dependencies (e.g. \fBmsvcrt.lib\fP). |
| .sp |
| This property is initialized by the value of |
| the \fBCMAKE_WINDOWS_EXPORT_ALL_SYMBOLS\fP variable if it is set |
| when a target is created. |
| .SS XCODE_ATTRIBUTE_<an\-attribute> |
| .sp |
| Set Xcode target attributes directly. |
| .sp |
| Tell the \fBXcode\fP generator to set \fB<an\-attribute>\fP to a given |
| value in the generated Xcode project. Ignored on other generators. |
| .sp |
| This offers low\-level control over the generated Xcode project file. |
| It is meant as a last resort for specifying settings that CMake does |
| not otherwise have a way to control. Although this can override a |
| setting CMake normally produces on its own, doing so bypasses CMake\(aqs |
| model of the project and can break things. |
| .sp |
| See the \fBCMAKE_XCODE_ATTRIBUTE_<an\-attribute>\fP variable |
| to set attributes on all targets in a directory tree. |
| .sp |
| Contents of \fBXCODE_ATTRIBUTE_<an\-attribute>\fP may use |
| "generator expressions" with the syntax \fB$<...>\fP\&. See the |
| \fBcmake\-generator\-expressions(7)\fP manual for available |
| expressions. See the \fBcmake\-buildsystem(7)\fP manual |
| for more on defining buildsystem properties. |
| .SS XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY |
| .sp |
| New in version 3.20. |
| |
| .sp |
| Tell the \fBXcode\fP generator to perform code signing for all the |
| frameworks and libraries that are embedded using the |
| \fBXCODE_EMBED_FRAMEWORKS\fP property. |
| .sp |
| New in version 3.21. |
| |
| .sp |
| This property was generalized to other types of embedded items. See |
| \fBXCODE_EMBED_<type>_CODE_SIGN_ON_COPY\fP for the more general form. |
| .SS XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY |
| .sp |
| New in version 3.20. |
| |
| .sp |
| Tell the \fBXcode\fP generator to remove headers from all the |
| frameworks that are embedded using the |
| \fBXCODE_EMBED_FRAMEWORKS\fP property. |
| .sp |
| New in version 3.21. |
| |
| .sp |
| This property was generalized to other types of embedded items. See |
| \fBXCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY\fP for the more |
| general form. |
| .SS XCODE_EMBED_<type> |
| .sp |
| New in version 3.20. |
| |
| .sp |
| Tell the \fBXcode\fP generator to embed the specified list of items into |
| the target bundle. \fB<type>\fP specifies the embed build phase to use. |
| See the Xcode documentation for the base location of each \fB<type>\fP\&. |
| .sp |
| The supported values for \fB<type>\fP are: |
| .INDENT 0.0 |
| .TP |
| .B \fBFRAMEWORKS\fP |
| The specified items will be added to the \fBEmbed Frameworks\fP build phase. |
| The items can be CMake target names or paths to frameworks or libraries. |
| .TP |
| .B \fBAPP_EXTENSIONS\fP |
| New in version 3.21. |
| |
| .sp |
| The specified items will be added to the \fBEmbed App Extensions\fP build phase. |
| They must be CMake target names. |
| .TP |
| .B \fBPLUGINS\fP |
| New in version 3.23. |
| |
| .sp |
| The specified items will be added to the \fBEmbed PlugIns\fP build phase. |
| They must be CMake target names. |
| .UNINDENT |
| .sp |
| See also \fBXCODE_EMBED_<type>_PATH\fP, |
| \fBXCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY\fP and |
| \fBXCODE_EMBED_<type>_CODE_SIGN_ON_COPY\fP\&. |
| .SS XCODE_EMBED_<type>_CODE_SIGN_ON_COPY |
| .sp |
| New in version 3.20. |
| |
| .sp |
| Boolean property used only by the \fBXcode\fP generator. It specifies |
| whether to perform code signing for the items that are embedded using the |
| \fBXCODE_EMBED_<type>\fP property. |
| .sp |
| The supported values for \fB<type>\fP are: |
| .sp |
| \fBFRAMEWORKS\fP |
| .INDENT 0.0 |
| .TP |
| .B \fBAPP_EXTENSIONS\fP |
| New in version 3.21. |
| |
| .TP |
| .B \fBPLUGINS\fP |
| New in version 3.23. |
| |
| .UNINDENT |
| .sp |
| If a \fBXCODE_EMBED_<type>_CODE_SIGN_ON_COPY\fP property is not defined on the |
| target, no code signing on copy will be performed for that \fB<type>\fP\&. |
| .SS XCODE_EMBED_<type>_PATH |
| .sp |
| New in version 3.20. |
| |
| .sp |
| This property is used only by the \fBXcode\fP generator. When defined, |
| it specifies the relative path to use when embedding the items specified by |
| \fBXCODE_EMBED_<type>\fP\&. The path is relative |
| to the base location of the \fBEmbed XXX\fP build phase associated with |
| \fB<type>\fP\&. See the Xcode documentation for the base location of each |
| \fB<type>\fP\&. |
| .sp |
| The supported values for \fB<type>\fP are: |
| .sp |
| \fBFRAMEWORKS\fP |
| .INDENT 0.0 |
| .TP |
| .B \fBAPP_EXTENSIONS\fP |
| New in version 3.21. |
| |
| .TP |
| .B \fBPLUGINS\fP |
| New in version 3.23. |
| |
| .UNINDENT |
| .SS XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY |
| .sp |
| New in version 3.20. |
| |
| .sp |
| Boolean property used only by the \fBXcode\fP generator. It specifies |
| whether to remove headers from all the frameworks that are embedded using the |
| \fBXCODE_EMBED_<type>\fP property. |
| .sp |
| The supported values for \fB<type>\fP are: |
| .INDENT 0.0 |
| .TP |
| .B \fBFRAMEWORKS\fP |
| If the \fBXCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY\fP property is not |
| defined, headers will not be removed on copy by default. |
| .TP |
| .B \fBAPP_EXTENSIONS\fP |
| New in version 3.21. |
| |
| .sp |
| If the \fBXCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY\fP property is not |
| defined, headers WILL be removed on copy by default. |
| .TP |
| .B \fBPLUGINS\fP |
| New in version 3.23. |
| |
| .UNINDENT |
| .SS XCODE_EXPLICIT_FILE_TYPE |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Set the Xcode \fBexplicitFileType\fP attribute on its reference to a |
| target. CMake computes a default based on target type but |
| can be told explicitly with this property. |
| .sp |
| See also \fBXCODE_PRODUCT_TYPE\fP\&. |
| .SS XCODE_GENERATE_SCHEME |
| .sp |
| New in version 3.15. |
| |
| .sp |
| If enabled, the \fBXcode\fP generator will generate schema files. These |
| are useful to invoke analyze, archive, build\-for\-testing and test |
| actions from the command line. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_GENERATE_SCHEME\fP if it is set when a target |
| is created. |
| .sp |
| The following target properties overwrite the default of the |
| corresponding settings on the "Diagnostic" tab for each schema file. |
| Each of those is initialized by the respective \fBCMAKE_\fP variable |
| at target creation time. |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_ADDRESS_SANITIZER\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_DYNAMIC_LIBRARY_LOADS\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_DYNAMIC_LINKER_API_USAGE\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_GUARD_MALLOC\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_MAIN_THREAD_CHECKER_STOP\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_MALLOC_GUARD_EDGES\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_MALLOC_SCRIBBLE\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_MALLOC_STACK\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_THREAD_SANITIZER\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_THREAD_SANITIZER_STOP\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_ZOMBIE_OBJECTS\fP |
| .UNINDENT |
| .sp |
| The following target properties will be applied on the |
| "Info", "Arguments", and "Options" tab: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_ARGUMENTS\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_DEBUG_AS_ROOT\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_ENVIRONMENT\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_EXECUTABLE\fP |
| .IP \(bu 2 |
| \fBXCODE_SCHEME_WORKING_DIRECTORY\fP |
| .UNINDENT |
| .SS XCODE_LINK_BUILD_PHASE_MODE |
| .sp |
| New in version 3.19. |
| |
| .sp |
| When using the \fBXcode\fP generator, libraries to be linked will be |
| specified in the Xcode project file using either the "Link Binary With |
| Libraries" build phase or directly as linker flags. The former allows Xcode |
| to manage build paths, which may be necessary when creating Xcode archives |
| because it may use different build paths to a regular build. |
| .sp |
| This property controls usage of "Link Binary With Libraries" build phase for |
| a target that is an app bundle, executable, shared library, shared framework |
| or a module library. |
| .sp |
| Possible values are: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBNONE\fP |
| The libraries will be linked by specifying the linker flags directly. |
| .IP \(bu 2 |
| \fBBUILT_ONLY\fP |
| The "Link Binary With Libraries" build phase will be used to link to another |
| target under the following conditions: |
| .INDENT 2.0 |
| .IP \(bu 2 |
| The target to be linked to is a regular non\-imported, non\-interface library |
| target. |
| .IP \(bu 2 |
| The output directory of the target being built has not been changed from |
| its default (see \fBRUNTIME_OUTPUT_DIRECTORY\fP and |
| \fBLIBRARY_OUTPUT_DIRECTORY\fP). |
| .UNINDENT |
| .IP \(bu 2 |
| \fBKNOWN_LOCATION\fP |
| The "Link Binary With Libraries" build phase will be used to link to another |
| target under the same conditions as with \fBBUILT_ONLY\fP and also: |
| .INDENT 2.0 |
| .IP \(bu 2 |
| Imported library targets except those of type \fBUNKNOWN\fP\&. |
| .IP \(bu 2 |
| Any non\-target library specified directly with a path. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| For all other cases, the libraries will be linked by specifying the linker |
| flags directly. |
| .sp |
| \fBWARNING:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Libraries linked using "Link Binary With Libraries" are linked after the |
| ones linked through regular linker flags. This order should be taken into |
| account when different static libraries contain symbols with the same name, |
| as the former ones will take precedence over the latter. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBWARNING:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| If two or more directories contain libraries with identical file names and |
| some libraries are linked from those directories, the library search path |
| lookup will end up linking libraries from the first directory. This is a |
| known limitation of Xcode. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This property is initialized by the value of the |
| \fBCMAKE_XCODE_LINK_BUILD_PHASE_MODE\fP variable if it is set when a |
| target is created. |
| .SS XCODE_PRODUCT_TYPE |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Set the Xcode \fBproductType\fP attribute on its reference to a |
| target. CMake computes a default based on target type but |
| can be told explicitly with this property. |
| .sp |
| See also \fBXCODE_EXPLICIT_FILE_TYPE\fP\&. |
| .SS XCODE_SCHEME_ADDRESS_SANITIZER |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Whether to enable \fBAddress Sanitizer\fP in the Diagnostics |
| section of the generated Xcode scheme. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_SCHEME_ADDRESS_SANITIZER\fP if it is set |
| when a target is created. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Whether to enable \fBDetect use of stack after return\fP |
| in the Diagnostics section of the generated Xcode scheme. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN\fP |
| if it is set when a target is created. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_ARGUMENTS |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Specify command line arguments that should be added to the Arguments |
| section of the generated Xcode scheme. |
| .sp |
| If set to a list of arguments those will be added to the scheme. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_DEBUG_AS_ROOT |
| .sp |
| New in version 3.15. |
| |
| .sp |
| Whether to debug the target as \(aqroot\(aq. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Whether to enable |
| \fBAllow debugging when using document Versions Browser\fP |
| in the Options section of the generated Xcode scheme. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING\fP |
| if it is set when a target is created. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE |
| .sp |
| New in version 3.23. |
| |
| .sp |
| Property value for \fBGPU Frame Capture\fP in the Options section of |
| the generated Xcode scheme. Example values are \fIMetal\fP and |
| \fIDisabled\fP\&. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE\fP |
| if it is set when a target is created. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Whether to disable the \fBMain Thread Checker\fP |
| in the Diagnostics section of the generated Xcode scheme. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER\fP |
| if it is set when a target is created. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Whether to enable \fBDynamic Library Loads\fP |
| in the Diagnostics section of the generated Xcode scheme. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS\fP if it is set |
| when a target is created. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Whether to enable \fBDynamic Linker API usage\fP |
| in the Diagnostics section of the generated Xcode scheme. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE\fP if it is set |
| when a target is created. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_ENVIRONMENT |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Specify environment variables that should be added to the Arguments |
| section of the generated Xcode scheme. |
| .sp |
| If set to a list of environment variables and values of the form |
| \fBMYVAR=value\fP those environment variables will be added to the |
| scheme. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_EXECUTABLE |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Specify path to executable in the Info section of the generated |
| Xcode scheme. If not set the schema generator will select the |
| current target if it is actually executable. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_GUARD_MALLOC |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Whether to enable \fBGuard Malloc\fP |
| in the Diagnostics section of the generated Xcode scheme. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_SCHEME_GUARD_MALLOC\fP if it is set |
| when a target is created. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Whether to enable the \fBMain Thread Checker\fP option |
| \fBPause on issues\fP |
| in the Diagnostics section of the generated Xcode scheme. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP\fP if it is set |
| when a target is created. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_MALLOC_GUARD_EDGES |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Whether to enable \fBMalloc Guard Edges\fP |
| in the Diagnostics section of the generated Xcode scheme. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES\fP if it is set |
| when a target is created. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_MALLOC_SCRIBBLE |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Whether to enable \fBMalloc Scribble\fP |
| in the Diagnostics section of the generated Xcode scheme. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE\fP if it is set |
| when a target is created. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_MALLOC_STACK |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Whether to enable \fBMalloc Stack\fP in the Diagnostics |
| section of the generated Xcode scheme. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_SCHEME_MALLOC_STACK\fP if it is set |
| when a target is created. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_THREAD_SANITIZER |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Whether to enable \fBThread Sanitizer\fP in the Diagnostics |
| section of the generated Xcode scheme. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_SCHEME_THREAD_SANITIZER\fP if it is set |
| when a target is created. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_THREAD_SANITIZER_STOP |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Whether to enable \fBThread Sanitizer \- Pause on issues\fP |
| in the Diagnostics section of the generated Xcode scheme. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP\fP if it is set |
| when a target is created. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Whether to enable \fBUndefined Behavior Sanitizer\fP |
| in the Diagnostics section of the generated Xcode scheme. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER\fP |
| if it is set when a target is created. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Whether to enable \fBUndefined Behavior Sanitizer\fP option |
| \fBPause on issues\fP |
| in the Diagnostics section of the generated Xcode scheme. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP\fP |
| if it is set when a target is created. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_WORKING_DIRECTORY |
| .sp |
| New in version 3.17. |
| |
| .sp |
| Specify the \fBWorking Directory\fP of the \fIRun\fP and \fIProfile\fP |
| actions in the generated Xcode scheme. In case the value contains |
| generator expressions those are evaluated. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_SCHEME_WORKING_DIRECTORY\fP if it is set |
| when a target is created. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCODE_SCHEME_ZOMBIE_OBJECTS |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Whether to enable \fBZombie Objects\fP |
| in the Diagnostics section of the generated Xcode scheme. |
| .sp |
| This property is initialized by the value of the variable |
| \fBCMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS\fP if it is set |
| when a target is created. |
| .sp |
| Please refer to the \fBXCODE_GENERATE_SCHEME\fP target property |
| documentation to see all Xcode schema related properties. |
| .SS XCTEST |
| .sp |
| New in version 3.3. |
| |
| .sp |
| This target is a XCTest CFBundle on the Mac. |
| .sp |
| This property will usually get set via the \fBxctest_add_bundle()\fP |
| macro in \fBFindXCTest\fP module. |
| .sp |
| If a module library target has this property set to true it will be |
| built as a CFBundle when built on the Mac. It will have the directory |
| structure required for a CFBundle. |
| .sp |
| This property depends on \fBBUNDLE\fP to be effective. |
| .SH PROPERTIES ON TESTS |
| .SS ATTACHED_FILES |
| .sp |
| Attach a list of files to a dashboard submission. |
| .sp |
| Set this property to a list of files that will be encoded and |
| submitted to the dashboard as an addition to the test result. |
| .SS ATTACHED_FILES_ON_FAIL |
| .sp |
| Attach a list of files to a dashboard submission if the test fails. |
| .sp |
| Same as \fBATTACHED_FILES\fP, but these files will only be |
| included if the test does not pass. |
| .SS COST |
| .sp |
| This property describes the cost of a test. When parallel testing is |
| enabled, tests in the test set will be run in descending order of cost. |
| Projects can explicitly define the cost of a test by setting this property |
| to a floating point value. |
| .sp |
| When the cost of a test is not defined by the project, |
| \fBctest\fP will initially use a default cost of \fB0\fP\&. |
| It computes a weighted average of the cost each time a test is run and |
| uses that as an improved estimate of the cost for the next run. The more |
| a test is re\-run in the same build directory, the more representative the |
| cost should become. |
| .SS DEPENDS |
| .sp |
| Specifies that this test should only be run after the specified list of tests. |
| .sp |
| Set this to a list of tests that must finish before this test is run. The |
| results of those tests are not considered, the dependency relationship is |
| purely for order of execution (i.e. it is really just a \fIrun after\fP |
| relationship). Consider using test fixtures with setup tests if a dependency |
| with successful completion is required (see \fBFIXTURES_REQUIRED\fP). |
| .SS Examples |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_test(NAME baseTest1 ...) |
| add_test(NAME baseTest2 ...) |
| add_test(NAME dependsTest12 ...) |
| |
| set_tests_properties(dependsTest12 PROPERTIES DEPENDS "baseTest1;baseTest2") |
| # dependsTest12 runs after baseTest1 and baseTest2, even if they fail |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS DISABLED |
| .sp |
| New in version 3.9. |
| |
| .sp |
| If set to \fBTrue\fP, the test will be skipped and its status will be \(aqNot Run\(aq. A |
| \fBDISABLED\fP test will not be counted in the total number of tests and its |
| completion status will be reported to CDash as \fBDisabled\fP\&. |
| .sp |
| A \fBDISABLED\fP test does not participate in test fixture dependency resolution. |
| If a \fBDISABLED\fP test has fixture requirements defined in its |
| \fBFIXTURES_REQUIRED\fP property, it will not cause setup or cleanup |
| tests for those fixtures to be added to the test set. |
| .sp |
| If a test with the \fBFIXTURES_SETUP\fP property set is \fBDISABLED\fP, |
| the fixture behavior will be as though that setup test was passing and any test |
| case requiring that fixture will still run. |
| .SS ENVIRONMENT |
| .sp |
| Specify environment variables that should be defined for running a test. |
| .sp |
| Set to a semicolon\-separated list list |
| of environment variables and values of the form \fBMYVAR=value\fP\&. |
| Those environment variables will be defined while running the test. |
| The environment changes from this property do not affect other tests. |
| .SS ENVIRONMENT_MODIFICATION |
| .sp |
| New in version 3.22. |
| |
| .sp |
| Specify environment variables that should be modified for running a test. Note |
| that the operations performed by this property are performed after the |
| \fBENVIRONMENT\fP property is already applied. |
| .sp |
| Set to a semicolon\-separated list of |
| environment variables and values of the form \fBMYVAR=OP:VALUE\fP, |
| where \fBMYVAR\fP is the case\-sensitive name of an environment variable |
| to be modified. Entries are considered in the order specified in the |
| property\(aqs value. The \fBOP\fP may be one of: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBreset\fP: Reset to the unmodified value, ignoring all modifications to |
| \fBMYVAR\fP prior to this entry. Note that this will reset the variable to |
| the value set by \fBENVIRONMENT\fP, if it was set, and otherwise |
| to its state from the rest of the CTest execution. |
| .IP \(bu 2 |
| \fBset\fP: Replaces the current value of \fBMYVAR\fP with \fBVALUE\fP\&. |
| .IP \(bu 2 |
| \fBunset\fP: Unsets the current value of \fBMYVAR\fP\&. |
| .IP \(bu 2 |
| \fBstring_append\fP: Appends \fBVALUE\fP to the current value of \fBMYVAR\fP\&. |
| .IP \(bu 2 |
| \fBstring_prepend\fP: Prepends \fBVALUE\fP to the current value of \fBMYVAR\fP\&. |
| .IP \(bu 2 |
| \fBpath_list_append\fP: Appends \fBVALUE\fP to the current value of \fBMYVAR\fP |
| using the host platform\(aqs path list separator (\fB;\fP on Windows and \fB:\fP |
| elsewhere). |
| .IP \(bu 2 |
| \fBpath_list_prepend\fP: Prepends \fBVALUE\fP to the current value of |
| \fBMYVAR\fP using the host platform\(aqs path list separator (\fB;\fP on Windows |
| and \fB:\fP elsewhere). |
| .IP \(bu 2 |
| \fBcmake_list_append\fP: Appends \fBVALUE\fP to the current value of \fBMYVAR\fP |
| using \fB;\fP as the separator. |
| .IP \(bu 2 |
| \fBcmake_list_prepend\fP: Prepends \fBVALUE\fP to the current value of |
| \fBMYVAR\fP using \fB;\fP as the separator. |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Unrecognized \fBOP\fP values will result in the test failing before it is |
| executed. This is so that future operations may be added without changing |
| valid behavior of existing tests. |
| .sp |
| The environment changes from this property do not affect other tests. |
| .SS FAIL_REGULAR_EXPRESSION |
| .sp |
| If the output matches this regular expression the test will fail, |
| regardless of the process exit code. |
| .sp |
| If set, if the output matches one of specified regular expressions, |
| the test will fail. Example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_tests_properties(mytest PROPERTIES |
| FAIL_REGULAR_EXPRESSION "[^a\-z]Error;ERROR;Failed" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBFAIL_REGULAR_EXPRESSION\fP expects a list of regular expressions. |
| .sp |
| See also the \fBPASS_REGULAR_EXPRESSION\fP and |
| \fBSKIP_REGULAR_EXPRESSION\fP test properties. |
| .SS FIXTURES_CLEANUP |
| .sp |
| New in version 3.7. |
| |
| .sp |
| Specifies a list of fixtures for which the test is to be treated as a cleanup |
| test. These fixture names are distinct from test case names and are not |
| required to have any similarity to the names of tests associated with them. |
| .sp |
| Fixture cleanup tests are ordinary tests with all of the usual test |
| functionality. Setting the \fBFIXTURES_CLEANUP\fP property for a test has two |
| primary effects: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| CTest will ensure the test executes after all other tests which list any of |
| the fixtures in its \fBFIXTURES_REQUIRED\fP property. |
| .IP \(bu 2 |
| If CTest is asked to run only a subset of tests (e.g. using regular |
| expressions or the \fB\-\-rerun\-failed\fP option) and the cleanup test is not in |
| the set of tests to run, it will automatically be added if any tests in the |
| set require any fixture listed in \fBFIXTURES_CLEANUP\fP\&. |
| .UNINDENT |
| .sp |
| A cleanup test can have multiple fixtures listed in its \fBFIXTURES_CLEANUP\fP |
| property. It will execute only once for the whole CTest run, not once for each |
| fixture. A fixture can also have more than one cleanup test defined. If there |
| are multiple cleanup tests for a fixture, projects can control their order with |
| the usual \fBDEPENDS\fP test property if necessary. |
| .sp |
| A cleanup test is allowed to require other fixtures, but not any fixture listed |
| in its \fBFIXTURES_CLEANUP\fP property. For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # Ok: Dependent fixture is different to cleanup |
| set_tests_properties(cleanupFoo PROPERTIES |
| FIXTURES_CLEANUP Foo |
| FIXTURES_REQUIRED Bar |
| ) |
| |
| # Error: cannot require same fixture as cleanup |
| set_tests_properties(cleanupFoo PROPERTIES |
| FIXTURES_CLEANUP Foo |
| FIXTURES_REQUIRED Foo |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Cleanup tests will execute even if setup or regular tests for that fixture fail |
| or are skipped. |
| .sp |
| See \fBFIXTURES_REQUIRED\fP for a more complete discussion of how to use |
| test fixtures. |
| .SS FIXTURES_REQUIRED |
| .sp |
| New in version 3.7. |
| |
| .sp |
| Specifies a list of fixtures the test requires. Fixture names are case |
| sensitive and they are not required to have any similarity to test names. |
| .sp |
| Fixtures are a way to attach setup and cleanup tasks to a set of tests. If a |
| test requires a given fixture, then all tests marked as setup tasks for that |
| fixture will be executed first (once for the whole set of tests, not once per |
| test requiring the fixture). After all tests requiring a particular fixture |
| have completed, CTest will ensure all tests marked as cleanup tasks for that |
| fixture are then executed. Tests are marked as setup tasks with the |
| \fBFIXTURES_SETUP\fP property and as cleanup tasks with the |
| \fBFIXTURES_CLEANUP\fP property. If any of a fixture\(aqs setup tests fail, |
| all tests listing that fixture in their \fBFIXTURES_REQUIRED\fP property will not |
| be executed. The cleanup tests for the fixture will always be executed, even if |
| some setup tests fail. |
| .sp |
| When CTest is asked to execute only a subset of tests (e.g. by the use of |
| regular expressions or when run with the \fB\-\-rerun\-failed\fP command line |
| option), it will automatically add any setup or cleanup tests for fixtures |
| required by any of the tests that are in the execution set. This behavior can |
| be overridden with the \fB\-FS\fP, \fB\-FC\fP and \fB\-FA\fP command line options to |
| \fBctest(1)\fP if desired. |
| .sp |
| Since setup and cleanup tasks are also tests, they can have an ordering |
| specified by the \fBDEPENDS\fP test property just like any other tests. |
| This can be exploited to implement setup or cleanup using multiple tests for a |
| single fixture to modularise setup or cleanup logic. |
| .sp |
| The concept of a fixture is different to that of a resource specified by |
| \fBRESOURCE_LOCK\fP, but they may be used together. A fixture defines a |
| set of tests which share setup and cleanup requirements, whereas a resource |
| lock has the effect of ensuring a particular set of tests do not run in |
| parallel. Some situations may need both, such as setting up a database, |
| serializing test access to that database and deleting the database again at the |
| end. For such cases, tests would populate both \fBFIXTURES_REQUIRED\fP and |
| \fBRESOURCE_LOCK\fP to combine the two behaviors. Names used for |
| \fBRESOURCE_LOCK\fP have no relationship with names of fixtures, so note |
| that a resource lock does not imply a fixture and vice versa. |
| .sp |
| Consider the following example which represents a database test scenario |
| similar to that mentioned above: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_test(NAME testsDone COMMAND emailResults) |
| add_test(NAME fooOnly COMMAND testFoo) |
| add_test(NAME dbOnly COMMAND testDb) |
| add_test(NAME dbWithFoo COMMAND testDbWithFoo) |
| add_test(NAME createDB COMMAND initDB) |
| add_test(NAME setupUsers COMMAND userCreation) |
| add_test(NAME cleanupDB COMMAND deleteDB) |
| add_test(NAME cleanupFoo COMMAND removeFoos) |
| |
| set_tests_properties(setupUsers PROPERTIES DEPENDS createDB) |
| |
| set_tests_properties(createDB PROPERTIES FIXTURES_SETUP DB) |
| set_tests_properties(setupUsers PROPERTIES FIXTURES_SETUP DB) |
| set_tests_properties(cleanupDB PROPERTIES FIXTURES_CLEANUP DB) |
| set_tests_properties(cleanupFoo PROPERTIES FIXTURES_CLEANUP Foo) |
| set_tests_properties(testsDone PROPERTIES FIXTURES_CLEANUP "DB;Foo") |
| |
| set_tests_properties(fooOnly PROPERTIES FIXTURES_REQUIRED Foo) |
| set_tests_properties(dbOnly PROPERTIES FIXTURES_REQUIRED DB) |
| set_tests_properties(dbWithFoo PROPERTIES FIXTURES_REQUIRED "DB;Foo") |
| |
| set_tests_properties(dbOnly dbWithFoo createDB setupUsers cleanupDB |
| PROPERTIES RESOURCE_LOCK DbAccess) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Key points from this example: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| Two fixtures are defined: \fBDB\fP and \fBFoo\fP\&. Tests can require a single |
| fixture as \fBfooOnly\fP and \fBdbOnly\fP do, or they can depend on multiple |
| fixtures like \fBdbWithFoo\fP does. |
| .IP \(bu 2 |
| A \fBDEPENDS\fP relationship is set up to ensure \fBsetupUsers\fP happens after |
| \fBcreateDB\fP, both of which are setup tests for the \fBDB\fP fixture and will |
| therefore be executed before the \fBdbOnly\fP and \fBdbWithFoo\fP tests |
| automatically. |
| .IP \(bu 2 |
| No explicit \fBDEPENDS\fP relationships were needed to make the setup tests run |
| before or the cleanup tests run after the regular tests. |
| .IP \(bu 2 |
| The \fBFoo\fP fixture has no setup tests defined, only a single cleanup test. |
| .IP \(bu 2 |
| \fBtestsDone\fP is a cleanup test for both the \fBDB\fP and \fBFoo\fP fixtures. |
| Therefore, it will only execute once regular tests for both fixtures have |
| finished (i.e. after \fBfooOnly\fP, \fBdbOnly\fP and \fBdbWithFoo\fP). No |
| \fBDEPENDS\fP relationship was specified for \fBtestsDone\fP, so it is free to |
| run before, after or concurrently with other cleanup tests for either |
| fixture. |
| .IP \(bu 2 |
| The setup and cleanup tests never list the fixtures they are for in their own |
| \fBFIXTURES_REQUIRED\fP property, as that would result in a dependency on |
| themselves and be considered an error. |
| .UNINDENT |
| .SS FIXTURES_SETUP |
| .sp |
| New in version 3.7. |
| |
| .sp |
| Specifies a list of fixtures for which the test is to be treated as a setup |
| test. These fixture names are distinct from test case names and are not |
| required to have any similarity to the names of tests associated with them. |
| .sp |
| Fixture setup tests are ordinary tests with all of the usual test |
| functionality. Setting the \fBFIXTURES_SETUP\fP property for a test has two |
| primary effects: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| CTest will ensure the test executes before any other test which lists the |
| fixture name(s) in its \fBFIXTURES_REQUIRED\fP property. |
| .IP \(bu 2 |
| If CTest is asked to run only a subset of tests (e.g. using regular |
| expressions or the \fB\-\-rerun\-failed\fP option) and the setup test is not in |
| the set of tests to run, it will automatically be added if any tests in the |
| set require any fixture listed in \fBFIXTURES_SETUP\fP\&. |
| .UNINDENT |
| .sp |
| A setup test can have multiple fixtures listed in its \fBFIXTURES_SETUP\fP |
| property. It will execute only once for the whole CTest run, not once for each |
| fixture. A fixture can also have more than one setup test defined. If there are |
| multiple setup tests for a fixture, projects can control their order with the |
| usual \fBDEPENDS\fP test property if necessary. |
| .sp |
| A setup test is allowed to require other fixtures, but not any fixture listed |
| in its \fBFIXTURES_SETUP\fP property. For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # Ok: dependent fixture is different to setup |
| set_tests_properties(setupFoo PROPERTIES |
| FIXTURES_SETUP Foo |
| FIXTURES_REQUIRED Bar |
| ) |
| |
| # Error: cannot require same fixture as setup |
| set_tests_properties(setupFoo PROPERTIES |
| FIXTURES_SETUP Foo |
| FIXTURES_REQUIRED Foo |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If any of a fixture\(aqs setup tests fail, none of the tests listing that fixture |
| in its \fBFIXTURES_REQUIRED\fP property will be run. Cleanup tests will, |
| however, still be executed. |
| .sp |
| See \fBFIXTURES_REQUIRED\fP for a more complete discussion of how to use |
| test fixtures. |
| .SS LABELS |
| .sp |
| Specify a list of text labels associated with a test. The labels are |
| reported in both the \fBctest\fP output summary and in dashboard submissions. |
| They can also be used to filter the set of tests to be executed (see the |
| \fBctest \-L\fP and \fBctest \-LE\fP CTest Options). |
| .sp |
| See Additional Labels for adding labels to a test dynamically during |
| test execution. |
| .SS MEASUREMENT |
| .sp |
| Specify a \fBCDASH\fP measurement and value to be reported for a test. |
| .sp |
| If set to a name then that name will be reported to \fBCDASH\fP as a named |
| measurement with a value of \fB1\fP\&. You may also specify a value by |
| setting \fBMEASUREMENT\fP to \fBmeasurement=value\fP\&. |
| .SS PASS_REGULAR_EXPRESSION |
| .sp |
| The output must match this regular expression for the test to pass. |
| The process exit code is ignored. |
| .sp |
| If set, the test output will be checked against the specified regular |
| expressions and at least one of the regular expressions has to match, |
| otherwise the test will fail. Example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_tests_properties(mytest PROPERTIES |
| PASS_REGULAR_EXPRESSION "TestPassed;All ok" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBPASS_REGULAR_EXPRESSION\fP expects a list of regular expressions. |
| .sp |
| See also the \fBFAIL_REGULAR_EXPRESSION\fP and |
| \fBSKIP_REGULAR_EXPRESSION\fP test properties. |
| .SS PROCESSOR_AFFINITY |
| .sp |
| New in version 3.12. |
| |
| .sp |
| Set to a true value to ask CTest to launch the test process with CPU affinity |
| for a fixed set of processors. If enabled and supported for the current |
| platform, CTest will choose a set of processors to place in the CPU affinity |
| mask when launching the test process. The number of processors in the set is |
| determined by the \fBPROCESSORS\fP test property or the number of |
| processors available to CTest, whichever is smaller. The set of processors |
| chosen will be disjoint from the processors assigned to other concurrently |
| running tests that also have the \fBPROCESSOR_AFFINITY\fP property enabled. |
| .SS PROCESSORS |
| .sp |
| Set to specify how many process slots this test requires. |
| If not set, the default is \fB1\fP processor. |
| .sp |
| Denotes the number of processors that this test will require. This is |
| typically used for MPI tests, and should be used in conjunction with |
| the \fBctest_test()\fP \fBPARALLEL_LEVEL\fP option. |
| .sp |
| This will also be used to display a weighted test timing result in label and |
| subproject summaries in the command line output of \fBctest(1)\fP\&. The wall |
| clock time for the test run will be multiplied by this property to give a |
| better idea of how much cpu resource CTest allocated for the test. |
| .sp |
| See also the \fBPROCESSOR_AFFINITY\fP test property. |
| .SS REQUIRED_FILES |
| .sp |
| List of files required to run the test. The filenames are relative to the |
| test \fBWORKING_DIRECTORY\fP unless an absolute path is specified. |
| .sp |
| If set to a list of files, the test will not be run unless all of the |
| files exist. |
| .SS Examples |
| .sp |
| Suppose that \fBtest.txt\fP is created by test \fBbaseTest\fP and \fBnone.txt\fP |
| does not exist: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_test(NAME baseTest ...) # Assumed to create test.txt |
| add_test(NAME fileTest ...) |
| |
| # The following ensures that if baseTest is successful, test.txt will |
| # have been created before fileTest is run |
| set_tests_properties(fileTest PROPERTIES |
| DEPENDS baseTest |
| REQUIRED_FILES test.txt |
| ) |
| |
| add_test(NAME notRunTest ...) |
| |
| # The following makes notRunTest depend on two files. Nothing creates |
| # the none.txt file, so notRunTest will fail with status "Not Run". |
| set_tests_properties(notRunTest PROPERTIES |
| REQUIRED_FILES "test.txt;none.txt" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The above example demonstrates how \fBREQUIRED_FILES\fP works, but it is not the |
| most robust way to implement test ordering with failure detection. For that, |
| test fixtures are a better alternative (see \fBFIXTURES_REQUIRED\fP). |
| .SS RESOURCE_GROUPS |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Specify resources required by a test, grouped in a way that is meaningful to |
| the test. See resource allocation |
| for more information on how this property integrates into the CTest resource |
| allocation feature. |
| .sp |
| The \fBRESOURCE_GROUPS\fP property is a semicolon\-separated list of group descriptions. Each entry consists of an optional |
| number of groups using the description followed by a series of resource |
| requirements for those groups. These requirements (and the number of groups) |
| are separated by commas. The resource requirements consist of the name of a |
| resource type, followed by a colon, followed by an unsigned integer |
| specifying the number of slots required on one resource of the given type. |
| .sp |
| The \fBRESOURCE_GROUPS\fP property tells CTest what resources a test expects |
| to use grouped in a way meaningful to the test. The test itself must read |
| the environment variables to |
| determine which resources have been allocated to each group. For example, |
| each group may correspond to a process the test will spawn when executed. |
| .sp |
| Consider the following example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_test(NAME MyTest COMMAND MyExe) |
| set_property(TEST MyTest PROPERTY RESOURCE_GROUPS |
| "2,gpus:2" |
| "gpus:4,crypto_chips:2") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In this example, there are two group descriptions (implicitly separated by a |
| semicolon.) The content of the first description is \fB2,gpus:2\fP\&. This |
| description specifies 2 groups, each of which requires 2 slots from a single |
| GPU. The content of the second description is \fBgpus:4,crypto_chips:2\fP\&. This |
| description does not specify a group count, so a default of 1 is assumed. |
| This single group requires 4 slots from a single GPU and 2 slots from a |
| single cryptography chip. In total, 3 resource groups are specified for this |
| test, each with its own unique requirements. |
| .sp |
| Note that the number of slots following the resource type specifies slots from |
| a \fIsingle\fP instance of the resource. If the resource group can tolerate |
| receiving slots from different instances of the same resource, it can indicate |
| this by splitting the specification into multiple requirements of one slot. For |
| example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_test(NAME MyTest COMMAND MyExe) |
| set_property(TEST MyTest PROPERTY RESOURCE_GROUPS |
| "gpus:1,gpus:1,gpus:1,gpus:1") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In this case, the single resource group indicates that it needs four GPU slots, |
| all of which may come from separate GPUs (though they don\(aqt have to; CTest may |
| still assign slots from the same GPU.) |
| .sp |
| When CTest sets the environment variables for a test, it assigns a group number |
| based on the group description, starting at 0 on the left and the number of |
| groups minus 1 on the right. For example, in the example above, the two |
| groups in the first description would have IDs of 0 and 1, and the single |
| group in the second description would have an ID of 2. |
| .sp |
| Both the \fBRESOURCE_GROUPS\fP and \fBRESOURCE_LOCK\fP properties serve |
| similar purposes, but they are distinct and orthogonal. Resources specified by |
| \fBRESOURCE_GROUPS\fP do not affect \fBRESOURCE_LOCK\fP, and vice versa. |
| Whereas \fBRESOURCE_LOCK\fP is a simpler property that is used for |
| locking one global resource, \fBRESOURCE_GROUPS\fP is a more advanced property |
| that allows multiple tests to simultaneously use multiple resources of the |
| same type, specifying their requirements in a fine\-grained manner. |
| .SS RESOURCE_LOCK |
| .sp |
| Specify a list of resources that are locked by this test. |
| .sp |
| If multiple tests specify the same resource lock, they are guaranteed |
| not to run concurrently. |
| .sp |
| See also \fBFIXTURES_REQUIRED\fP if the resource requires any setup or |
| cleanup steps. |
| .sp |
| Both the \fBRESOURCE_GROUPS\fP and \fBRESOURCE_LOCK\fP properties serve |
| similar purposes, but they are distinct and orthogonal. Resources specified by |
| \fBRESOURCE_GROUPS\fP do not affect \fBRESOURCE_LOCK\fP, and vice versa. |
| Whereas \fBRESOURCE_LOCK\fP is a simpler property that is used for locking one |
| global resource, \fBRESOURCE_GROUPS\fP is a more advanced property |
| that allows multiple tests to simultaneously use multiple resources of the |
| same type, specifying their requirements in a fine\-grained manner. |
| .SS RUN_SERIAL |
| .sp |
| Do not run this test in parallel with any other test. |
| .sp |
| Use this option in conjunction with the ctest_test \fBPARALLEL_LEVEL\fP |
| option to specify that this test should not be run in parallel with |
| any other tests. |
| .SS SKIP_REGULAR_EXPRESSION |
| .sp |
| New in version 3.16. |
| |
| .sp |
| If the output matches this regular expression the test will be marked as skipped. |
| .sp |
| If set, if the output matches one of specified regular expressions, |
| the test will be marked as skipped. Example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(TEST mytest PROPERTY |
| SKIP_REGULAR_EXPRESSION "[^a\-z]Skip" "SKIP" "Skipped" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBSKIP_REGULAR_EXPRESSION\fP expects a list of regular expressions. |
| .sp |
| See also the \fBSKIP_RETURN_CODE\fP, |
| \fBPASS_REGULAR_EXPRESSION\fP, and \fBFAIL_REGULAR_EXPRESSION\fP |
| test properties. |
| .SS SKIP_RETURN_CODE |
| .sp |
| Return code to mark a test as skipped. |
| .sp |
| Sometimes only a test itself can determine if all requirements for the |
| test are met. If such a situation should not be considered a hard failure |
| a return code of the process can be specified that will mark the test as |
| \fBNot Run\fP if it is encountered. Valid values are in the range of |
| 0 to 255, inclusive. |
| .sp |
| See also the \fBSKIP_REGULAR_EXPRESSION\fP property. |
| .SS TIMEOUT |
| .sp |
| How many seconds to allow for this test. |
| .sp |
| This property if set will limit a test to not take more than the |
| specified number of seconds to run. If it exceeds that the test |
| process will be killed and ctest will move to the next test. This |
| setting takes precedence over \fBCTEST_TEST_TIMEOUT\fP\&. |
| .SS TIMEOUT_AFTER_MATCH |
| .sp |
| New in version 3.6. |
| |
| .sp |
| Change a test\(aqs timeout duration after a matching line is encountered |
| in its output. |
| .SS Usage |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_test(mytest ...) |
| set_property(TEST mytest PROPERTY TIMEOUT_AFTER_MATCH "${seconds}" "${regex}") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Description |
| .sp |
| Allow a test \fBseconds\fP to complete after \fBregex\fP is encountered in |
| its output. |
| .sp |
| When the test outputs a line that matches \fBregex\fP its start time is |
| reset to the current time and its timeout duration is changed to |
| \fBseconds\fP\&. Prior to this, the timeout duration is determined by the |
| \fBTIMEOUT\fP property or the \fBCTEST_TEST_TIMEOUT\fP |
| variable if either of these are set. Because the test\(aqs start time is |
| reset, its execution time will not include any time that was spent |
| waiting for the matching output. |
| .sp |
| \fI\%TIMEOUT_AFTER_MATCH\fP is useful for avoiding spurious |
| timeouts when your test must wait for some system resource to become |
| available before it can execute. Set \fBTIMEOUT\fP to a longer |
| duration that accounts for resource acquisition and use |
| \fI\%TIMEOUT_AFTER_MATCH\fP to control how long the actual test |
| is allowed to run. |
| .sp |
| If the required resource can be controlled by CTest you should use |
| \fBRESOURCE_LOCK\fP instead of \fI\%TIMEOUT_AFTER_MATCH\fP\&. |
| This property should be used when only the test itself can determine |
| when its required resources are available. |
| .SS WILL_FAIL |
| .sp |
| If set to true, this will invert the pass/fail flag of the test. |
| .sp |
| This property can be used for tests that are expected to fail and |
| return a non zero return code. |
| .SS WORKING_DIRECTORY |
| .sp |
| The directory from which the test executable will be called. |
| .sp |
| If this is not set, the test will be run with the working directory set to the |
| binary directory associated with where the test was created (i.e. the |
| \fBCMAKE_CURRENT_BINARY_DIR\fP for where \fBadd_test()\fP was |
| called). |
| .SH PROPERTIES ON SOURCE FILES |
| .SS ABSTRACT |
| .sp |
| Is this source file an abstract class. |
| .sp |
| A property on a source file that indicates if the source file |
| represents a class that is abstract. This only makes sense for |
| languages that have a notion of an abstract class and it is only used |
| by some tools that wrap classes into other languages. |
| .SS AUTORCC_OPTIONS |
| .sp |
| Additional options for \fBrcc\fP when using \fBAUTORCC\fP |
| .sp |
| This property holds additional command line options which will be used when |
| \fBrcc\fP is executed during the build via \fBAUTORCC\fP, i.e. it is equivalent to the |
| optional \fBOPTIONS\fP argument of the \fBqt4_add_resources()\fP macro. |
| .sp |
| By default it is empty. |
| .sp |
| The options set on the \fB\&.qrc\fP source file may override |
| \fBAUTORCC_OPTIONS\fP set on the target. |
| .SS EXAMPLE |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # ... |
| set_property(SOURCE resources.qrc PROPERTY AUTORCC_OPTIONS "\-\-compress;9") |
| # ... |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS AUTOUIC_OPTIONS |
| .sp |
| Additional options for \fBuic\fP when using \fBAUTOUIC\fP |
| .sp |
| This property holds additional command line options |
| which will be used when \fBuic\fP is executed during the build via |
| \fBAUTOUIC\fP, i.e. it is equivalent to the optional \fBOPTIONS\fP |
| argument of the \fBqt4_wrap_ui()\fP macro. |
| .sp |
| By default it is empty. |
| .sp |
| The options set on the \fB\&.ui\fP source file may override |
| \fBAUTOUIC_OPTIONS\fP set on the target. |
| .SS EXAMPLE |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # ... |
| set_property(SOURCE widget.ui PROPERTY AUTOUIC_OPTIONS "\-\-no\-protection") |
| # ... |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS COMPILE_DEFINITIONS |
| .sp |
| Preprocessor definitions for compiling a source file. |
| .sp |
| The \fBCOMPILE_DEFINITIONS\fP property may be set to a semicolon\-separated |
| list of preprocessor definitions using the syntax \fBVAR\fP or \fBVAR=value\fP\&. |
| Function\-style definitions are not supported. CMake will |
| automatically escape the value correctly for the native build system |
| (note that CMake language syntax may require escapes to specify some |
| values). This property may be set on a per\-configuration basis using |
| the name \fBCOMPILE_DEFINITIONS_<CONFIG>\fP where \fB<CONFIG>\fP is an upper\-case |
| name (ex. \fBCOMPILE_DEFINITIONS_DEBUG\fP). |
| .sp |
| CMake will automatically drop some definitions that are not supported |
| by the native build tool. Xcode does not support per\-configuration |
| definitions on source files. |
| .sp |
| Disclaimer: Most native build tools have poor support for escaping |
| certain values. CMake has work\-arounds for many cases but some values |
| may just not be possible to pass correctly. If a value does not seem |
| to be escaped correctly, do not attempt to work\-around the problem by |
| adding escape sequences to the value. Your work\-around may break in a |
| future version of CMake that has improved escape support. Instead |
| consider defining the macro in a (configured) header file. Then |
| report the limitation. Known limitations include: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # \- broken almost everywhere |
| ; \- broken in VS IDE 7.0 and Borland Makefiles |
| , \- broken in VS IDE |
| % \- broken in some cases in NMake |
| & | \- broken in some cases on MinGW |
| ^ < > \e" \- broken in most Make tools on Windows |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| CMake does not reject these values outright because they do work in |
| some cases. Use with caution. |
| .sp |
| Contents of \fBCOMPILE_DEFINITIONS\fP may use \fBcmake\-generator\-expressions(7)\fP |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. However, \fBXcode\fP |
| does not support per\-config per\-source settings, so expressions |
| that depend on the build configuration are not allowed with that |
| generator. |
| .sp |
| Generator expressions should be preferred instead of setting the alternative per\-configuration |
| property. |
| .SS COMPILE_FLAGS |
| .sp |
| Additional flags to be added when compiling this source file. |
| .sp |
| The \fBCOMPILE_FLAGS\fP property, managed as a string, sets additional compiler |
| flags used that will be added to the list of compile flags when this source |
| file builds. The flags will be added after target\-wide flags (except in |
| some cases not supported by the \fBVisual Studio 9 2008\fP generator). |
| .sp |
| Use \fBCOMPILE_DEFINITIONS\fP to pass additional preprocessor definitions. |
| .sp |
| Contents of \fBCOMPILE_FLAGS\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. However, \fBXcode\fP |
| does not support per\-config per\-source settings, so expressions |
| that depend on the build configuration are not allowed with that |
| generator. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This property has been superseded by the \fBCOMPILE_OPTIONS\fP property. |
| .UNINDENT |
| .UNINDENT |
| .SS COMPILE_OPTIONS |
| .sp |
| New in version 3.11. |
| |
| .sp |
| List of additional options to pass to the compiler. |
| .sp |
| This property holds a semicolon\-separated list |
| of options and will be added to the list of compile flags when this source |
| file builds. The options will be added after target\-wide options (except in |
| some cases not supported by the \fBVisual Studio 9 2008\fP generator). |
| .sp |
| Contents of \fBCOMPILE_OPTIONS\fP may use "generator expressions" with the |
| syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP manual |
| for available expressions. However, \fBXcode\fP |
| does not support per\-config per\-source settings, so expressions |
| that depend on the build configuration are not allowed with that |
| generator. |
| .sp |
| Usage example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_source_files_properties(foo.cpp PROPERTIES COMPILE_OPTIONS "\-Wno\-unused\-parameter;\-Wno\-missing\-field\-initializer") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Related properties: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| Prefer this property over \fBCOMPILE_FLAGS\fP\&. |
| .IP \(bu 2 |
| Use \fBCOMPILE_DEFINITIONS\fP to pass additional preprocessor definitions. |
| .IP \(bu 2 |
| Use \fBINCLUDE_DIRECTORIES\fP to pass additional include directories. |
| .UNINDENT |
| .sp |
| Related commands: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBadd_compile_options()\fP for directory\-wide settings |
| .IP \(bu 2 |
| \fBtarget_compile_options()\fP for target\-specific settings |
| .UNINDENT |
| .SS EXTERNAL_OBJECT |
| .sp |
| If set to true then this is an object file. |
| .sp |
| If this property is set to \fBTrue\fP then the source file is really an |
| object file and should not be compiled. It will still be linked into |
| the target though. |
| .SS Fortran_FORMAT |
| .sp |
| Set to \fBFIXED\fP or \fBFREE\fP to indicate the Fortran source layout. |
| .sp |
| This property tells CMake whether a given Fortran source file uses |
| fixed\-format or free\-format. CMake will pass the corresponding format flag |
| to the compiler. Consider using the target\-wide \fBFortran_FORMAT\fP |
| property if all source files in a target share the same format. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| For some compilers, \fBNAG\fP, \fBPGI\fP and \fBSolaris Studio\fP, |
| setting this to \fBOFF\fP will have no effect. |
| .UNINDENT |
| .UNINDENT |
| .SS Fortran_PREPROCESS |
| .sp |
| New in version 3.18. |
| |
| .sp |
| Control whether the Fortran source file should be unconditionally preprocessed. |
| .sp |
| If unset or empty, rely on the compiler to determine whether the file |
| should be preprocessed. If explicitly set to \fBOFF\fP then the file |
| does not need to be preprocessed. If explicitly set to \fBON\fP, then |
| the file does need to be preprocessed as part of the compilation step. |
| .sp |
| When using the \fBNinja\fP generator, all source files are |
| first preprocessed in order to generate module dependency |
| information. Setting this property to \fBOFF\fP will make \fBNinja\fP |
| skip this step. |
| .sp |
| Consider using the target\-wide \fBFortran_PREPROCESS\fP property |
| if all source files in a target need to be preprocessed. |
| .SS GENERATED |
| .sp |
| Is this source file generated as part of the build or CMake process. |
| .sp |
| Changed in version 3.20: The GENERATED source file property is now visible in all directories. |
| |
| .sp |
| Tells the internal CMake engine that a source file is generated by an outside |
| process such as another build step, or the execution of CMake itself. |
| This information is then used to exempt the file from any existence or |
| validity checks. |
| .sp |
| Any file that is |
| .INDENT 0.0 |
| .IP \(bu 2 |
| created by the execution of commands such as |
| \fBadd_custom_command()\fP and \fBfile(GENERATE)\fP |
| .IP \(bu 2 |
| listed as one of the \fBBYPRODUCTS\fP of an \fBadd_custom_command()\fP |
| or \fBadd_custom_target()\fP command, or |
| .IP \(bu 2 |
| created by a CMake \fBAUTOGEN\fP operation such as \fBAUTOMOC\fP, |
| \fBAUTORCC\fP, or \fBAUTOUIC\fP |
| .UNINDENT |
| .sp |
| will be marked with the \fBGENERATED\fP property. |
| .sp |
| When a generated file created as the \fBOUTPUT\fP of an |
| \fBadd_custom_command()\fP command is explicitly listed as a source file |
| for any target in the same directory scope (which usually means the same |
| \fBCMakeLists.txt\fP file), CMake will automatically create a dependency to |
| make sure the file is generated before building that target. |
| .sp |
| The Makefile Generators will remove \fBGENERATED\fP files during |
| \fBmake clean\fP\&. |
| .sp |
| Generated sources may be hidden in some IDE tools, while in others they might |
| be shown. For the special case of sources generated by CMake\(aqs \fBAUTOMOC\fP, |
| \fBAUTORCC\fP or \fBAUTOUIC\fP functionality, the |
| \fBAUTOGEN_SOURCE_GROUP\fP, \fBAUTOMOC_SOURCE_GROUP\fP, |
| \fBAUTORCC_SOURCE_GROUP\fP and \fBAUTOUIC_SOURCE_GROUP\fP target |
| properties may influence where the generated sources are grouped in the project\(aqs |
| file lists. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Starting with CMake 3.20 the \fBGENERATED\fP source file property can be set |
| and retrieved from any directory scope. It is an all\-or\-nothing property. |
| It also can no longer be removed or unset if it was set to \fBTRUE\fP\&. Policy |
| \fBCMP0118\fP was introduced to allow supporting the \fBOLD\fP behavior |
| for some time. |
| .UNINDENT |
| .UNINDENT |
| .SS HEADER_FILE_ONLY |
| .sp |
| Is this source file only a header file. |
| .sp |
| A property on a source file that indicates if the source file is a |
| header file with no associated implementation. This is set |
| automatically based on the file extension and is used by CMake to |
| determine if certain dependency information should be computed. |
| .sp |
| By setting this property to \fBON\fP, you can disable compilation of |
| the given source file, even if it should be compiled because it is |
| part of the library\(aqs/executable\(aqs sources. |
| .sp |
| This is useful if you have some source files which you somehow |
| pre\-process, and then add these pre\-processed sources via |
| \fBadd_library()\fP or \fBadd_executable()\fP\&. Normally, in IDE, |
| there would be no reference of the original sources, only of these |
| pre\-processed sources. So by setting this property for all the original |
| source files to \fBON\fP, and then either calling \fBadd_library()\fP |
| or \fBadd_executable()\fP while passing both the pre\-processed |
| sources and the original sources, or by using \fBtarget_sources()\fP |
| to add original source files will do exactly what would one expect, i.e. |
| the original source files would be visible in IDE, and will not be built. |
| .SS INCLUDE_DIRECTORIES |
| .sp |
| New in version 3.11. |
| |
| .sp |
| List of preprocessor include file search directories. |
| .sp |
| This property holds a semicolon\-separated list of paths |
| and will be added to the list of include directories when this |
| source file builds. These directories will take precedence over directories |
| defined at target level except for \fBXcode\fP generator due to technical |
| limitations. |
| .sp |
| Relative paths should not be added to this property directly. |
| .sp |
| Contents of \fBINCLUDE_DIRECTORIES\fP may use "generator expressions" with |
| the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP manual |
| for available expressions. However, \fBXcode\fP does not support |
| per\-config per\-source settings, so expressions that depend on the build |
| configuration are not allowed with that generator. |
| .SS KEEP_EXTENSION |
| .sp |
| Make the output file have the same extension as the source file. |
| .sp |
| If this property is set then the file extension of the output file |
| will be the same as that of the source file. Normally the output file |
| extension is computed based on the language of the source file, for |
| example \fB\&.cxx\fP will go to a \fB\&.o\fP extension. |
| .SS LABELS |
| .sp |
| Specify a list of text labels associated with a source file. |
| .sp |
| This property has meaning only when the source file is listed in a |
| target whose \fBLABELS\fP property is also set. No other semantics are |
| currently specified. |
| .SS LANGUAGE |
| .sp |
| Specify the programming language in which a source file is written. |
| .sp |
| A property that can be set to indicate what programming language the |
| source file is. If it is not set the language is determined based on |
| the file extension. Typical values are \fBCXX\fP (i.e. C++), \fBC\fP, |
| \fBCSharp\fP, \fBCUDA\fP, \fBFortran\fP, \fBHIP\fP, \fBISPC\fP, and \fBASM\fP\&. Setting |
| this property for a file means this file will be compiled, unless |
| \fBHEADER_FILE_ONLY\fP is set. |
| .sp |
| Changed in version 3.20: Setting this property causes the source file to be compiled as the |
| specified language, using explicit flags if possible. Previously it |
| only caused the specified language\(aqs compiler to be used. |
| See policy \fBCMP0119\fP\&. |
| |
| .SS LOCATION |
| .sp |
| The full path to a source file. |
| .sp |
| A read only property on a SOURCE FILE that contains the full path to |
| the source file. |
| .SS MACOSX_PACKAGE_LOCATION |
| .sp |
| Place a source file inside a Application Bundle |
| (\fBMACOSX_BUNDLE\fP), Core Foundation Bundle (\fBBUNDLE\fP), |
| or Framework Bundle (\fBFRAMEWORK\fP). It is applicable for macOS |
| and iOS. |
| .sp |
| Executable targets with the \fBMACOSX_BUNDLE\fP property set are |
| built as macOS or iOS application bundles on Apple platforms. Shared |
| library targets with the \fBFRAMEWORK\fP property set are built as |
| macOS or iOS frameworks on Apple platforms. Module library targets with |
| the \fBBUNDLE\fP property set are built as macOS \fBCFBundle\fP bundles |
| on Apple platforms. Source files listed in the target with this property |
| set will be copied to a directory inside the bundle or framework content |
| folder specified by the property value. For macOS Application Bundles the |
| content folder is \fB<name>.app/Contents\fP\&. For macOS Frameworks the |
| content folder is \fB<name>.framework/Versions/<version>\fP\&. For macOS |
| CFBundles the content folder is \fB<name>.bundle/Contents\fP (unless the |
| extension is changed). See the \fBPUBLIC_HEADER\fP, |
| \fBPRIVATE_HEADER\fP, and \fBRESOURCE\fP target properties for |
| specifying files meant for \fBHeaders\fP, \fBPrivateHeaders\fP, or |
| \fBResources\fP directories. |
| .sp |
| If the specified location is equal to \fBResources\fP, the resulting location |
| will be the same as if the \fBRESOURCE\fP property had been used. If |
| the specified location is a sub\-folder of \fBResources\fP, it will be placed |
| into the respective sub\-folder. Note: For iOS Apple uses a flat bundle layout |
| where no \fBResources\fP folder exist. Therefore CMake strips the \fBResources\fP |
| folder name from the specified location. |
| .SS OBJECT_DEPENDS |
| .sp |
| Additional files on which a compiled object file depends. |
| .sp |
| Specifies a semicolon\-separated list of full\-paths to |
| files on which any object files compiled from this source file depend. |
| On Makefile Generators and the \fBNinja\fP generator an |
| object file will be recompiled if any of the named files is newer than it. |
| Visual Studio Generators and the \fBXcode\fP generator |
| cannot implement such compilation dependencies. |
| .sp |
| This property need not be used to specify the dependency of a source |
| file on a generated header file that it includes. Although the |
| property was originally introduced for this purpose, it is no longer |
| necessary. If the generated header file is created by a custom |
| command in the same target as the source file, the automatic |
| dependency scanning process will recognize the dependency. If the |
| generated header file is created by another target, an inter\-target |
| dependency should be created with the \fBadd_dependencies()\fP |
| command (if one does not already exist due to linking relationships). |
| .SS OBJECT_OUTPUTS |
| .sp |
| Additional outputs for a \fBNinja\fP or Makefile Generators rule. |
| .sp |
| Additional outputs created by compilation of this source file. If any |
| of these outputs is missing the object will be recompiled. This is |
| supported only on the \fBNinja\fP and Makefile Generators |
| and will be ignored on other generators. |
| .sp |
| This property supports |
| \fBgenerator expressions\fP\&. |
| .SS SKIP_AUTOGEN |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Exclude the source file from \fBAUTOMOC\fP, \fBAUTOUIC\fP and |
| \fBAUTORCC\fP processing (for Qt projects). |
| .sp |
| For finer exclusion control see \fBSKIP_AUTOMOC\fP, |
| \fBSKIP_AUTOUIC\fP and \fBSKIP_AUTORCC\fP\&. |
| .SS EXAMPLE |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # ... |
| set_property(SOURCE file.h PROPERTY SKIP_AUTOGEN ON) |
| # ... |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS SKIP_AUTOMOC |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Exclude the source file from \fBAUTOMOC\fP processing (for Qt projects). |
| .sp |
| For broader exclusion control see \fBSKIP_AUTOGEN\fP\&. |
| .SS EXAMPLE |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # ... |
| set_property(SOURCE file.h PROPERTY SKIP_AUTOMOC ON) |
| # ... |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS SKIP_AUTORCC |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Exclude the source file from \fBAUTORCC\fP processing (for Qt projects). |
| .sp |
| For broader exclusion control see \fBSKIP_AUTOGEN\fP\&. |
| .SS EXAMPLE |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # ... |
| set_property(SOURCE file.qrc PROPERTY SKIP_AUTORCC ON) |
| # ... |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS SKIP_AUTOUIC |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Exclude the source file from \fBAUTOUIC\fP processing (for Qt projects). |
| .sp |
| \fI\%SKIP_AUTOUIC\fP can be set on C++ header and source files and on |
| \fB\&.ui\fP files. |
| .sp |
| For broader exclusion control see \fBSKIP_AUTOGEN\fP\&. |
| .SS EXAMPLE |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # ... |
| set_property(SOURCE file.h PROPERTY SKIP_AUTOUIC ON) |
| set_property(SOURCE file.cpp PROPERTY SKIP_AUTOUIC ON) |
| set_property(SOURCE widget.ui PROPERTY SKIP_AUTOUIC ON) |
| # ... |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS SKIP_PRECOMPILE_HEADERS |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Is this source file skipped by \fBPRECOMPILE_HEADERS\fP feature. |
| .sp |
| This property helps with build problems that one would run into |
| when using the \fBPRECOMPILE_HEADERS\fP feature. |
| .sp |
| One example would be the usage of Objective\-C (\fB*.m\fP) files, and |
| Objective\-C++ (\fB*.mm\fP) files, which lead to compilation failure |
| because they are treated (in case of Ninja / Makefile generator) |
| as C, and CXX respectively. The precompile headers are not |
| compatible between languages. |
| .SS SKIP_UNITY_BUILD_INCLUSION |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Setting this property to true ensures the source file will be skipped by |
| unity builds when its associated target has its \fBUNITY_BUILD\fP |
| property set to true. The source file will instead be compiled on its own |
| in the same way as it would with unity builds disabled. |
| .sp |
| This property helps with "ODR (One definition rule)" problems where combining |
| a particular source file with others might lead to build errors or other |
| unintended side effects. |
| .SS Swift_DEPENDENCIES_FILE |
| .sp |
| New in version 3.15. |
| |
| .sp |
| This property sets the path for the Swift dependency file (swiftdeps) for the |
| source. If one is not specified, it will default to \fB<OBJECT>.swiftdeps\fP\&. |
| .SS Swift_DIAGNOSTICS_FILE |
| .sp |
| New in version 3.15. |
| |
| .sp |
| This property controls where the Swift diagnostics are serialized. |
| .SS SYMBOLIC |
| .sp |
| Is this just a name for a rule. |
| .sp |
| If \fBSYMBOLIC\fP (boolean) is set to \fBTrue\fP the build system will be informed |
| that the source file is not actually created on disk but instead used |
| as a symbolic name for a build rule. |
| .SS UNITY_GROUP |
| .sp |
| New in version 3.18. |
| |
| .sp |
| This property controls which \fIbucket\fP the source will be part of when |
| the \fBUNITY_BUILD_MODE\fP is set to \fBGROUP\fP\&. |
| .SS VS_COPY_TO_OUT_DIR |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Sets the \fB<CopyToOutputDirectory>\fP tag for a source file in a |
| Visual Studio project file. Valid values are \fBNever\fP, \fBAlways\fP |
| and \fBPreserveNewest\fP\&. |
| .SS VS_CSHARP_<tagname> |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Visual Studio and CSharp source\-file\-specific configuration. |
| .sp |
| Tell the \fBVisual Studio generators\fP |
| to set the source file tag \fB<tagname>\fP |
| to a given value in the generated Visual Studio CSharp |
| project. Ignored on other generators and languages. This property |
| can be used to define dependencies between source files or set any |
| other Visual Studio specific parameters. |
| .sp |
| Example usage: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_source_files_property(<filename> |
| PROPERTIES |
| VS_CSHARP_DependentUpon <other file> |
| VS_CSHARP_SubType "Form") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS VS_DEPLOYMENT_CONTENT |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Mark a source file as content for deployment with a Windows Phone or |
| Windows Store application when built with a |
| \fBVisual Studio generators\fP\&. |
| The value must evaluate to either \fB1\fP or \fB0\fP and may use |
| \fBgenerator expressions\fP |
| to make the choice based on the build configuration. |
| The \fB\&.vcxproj\fP file entry for the source file will be |
| marked either \fBDeploymentContent\fP or \fBExcludedFromBuild\fP |
| for values \fB1\fP and \fB0\fP, respectively. |
| .SS VS_DEPLOYMENT_LOCATION |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Specifies the deployment location for a content source file with a Windows |
| Phone or Windows Store application when built |
| with a \fBVisual Studio generators\fP\&. |
| This property is only applicable when using \fBVS_DEPLOYMENT_CONTENT\fP\&. |
| The value represent the path relative to the app package and applies to all |
| configurations. |
| .SS VS_INCLUDE_IN_VSIX |
| .sp |
| New in version 3.8. |
| |
| .sp |
| Boolean property to specify if the file should be included within a |
| VSIX (Visual Studio Integration Extension) extension package. |
| This is needed for development of Visual Studio extensions. |
| .SS VS_RESOURCE_GENERATOR |
| .sp |
| New in version 3.8. |
| |
| .sp |
| This property allows to specify the resource generator to be used |
| on this file. It defaults to \fBPublicResXFileCodeGenerator\fP if |
| not set. |
| .sp |
| This property only applies to C# projects. |
| .SS VS_SETTINGS |
| .sp |
| New in version 3.18. |
| |
| .sp |
| Set any item metadata on a file. |
| .sp |
| New in version 3.22: This property is honored for all source file types. |
| Previously it worked only for non\-built files. |
| |
| .sp |
| Takes a list of \fBKey=Value\fP pairs. Tells the Visual Studio generator to set |
| \fBKey\fP to \fBValue\fP as item metadata on the file. |
| .sp |
| For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(SOURCE file.hlsl PROPERTY VS_SETTINGS "Key=Value" "Key2=Value2") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| will set \fBKey\fP to \fBValue\fP and \fBKey2\fP to \fBValue2\fP on the |
| \fBfile.hlsl\fP item as metadata. |
| .sp |
| \fBGenerator expressions\fP are supported. |
| .SS VS_SHADER_DISABLE_OPTIMIZATIONS |
| .sp |
| New in version 3.11. |
| |
| .sp |
| Disable compiler optimizations for an \fB\&.hlsl\fP source file. This adds the |
| \fB\-Od\fP flag to the command line for the FxCompiler tool. Specify the value |
| \fBtrue\fP for this property to disable compiler optimizations. |
| .SS VS_SHADER_ENABLE_DEBUG |
| .sp |
| New in version 3.11. |
| |
| .sp |
| Enable debugging information for an \fB\&.hlsl\fP source file. This adds the |
| \fB\-Zi\fP flag to the command line for the FxCompiler tool. Specify the value |
| \fBtrue\fP to generate debugging information for the compiled shader. |
| .SS VS_SHADER_ENTRYPOINT |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Specifies the name of the entry point for the shader of a \fB\&.hlsl\fP source |
| file. |
| .SS VS_SHADER_FLAGS |
| .sp |
| New in version 3.2. |
| |
| .sp |
| Set additional Visual Studio shader flags of a \fB\&.hlsl\fP source file. |
| .SS VS_SHADER_MODEL |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Specifies the shader model of a \fB\&.hlsl\fP source file. Some shader types can |
| only be used with recent shader models |
| .SS VS_SHADER_OBJECT_FILE_NAME |
| .sp |
| New in version 3.12. |
| |
| .sp |
| Specifies a file name for the compiled shader object file for an \fB\&.hlsl\fP |
| source file. This adds the \fB\-Fo\fP flag to the command line for the FxCompiler |
| tool. |
| .SS VS_SHADER_OUTPUT_HEADER_FILE |
| .sp |
| New in version 3.10. |
| |
| .sp |
| Set filename for output header file containing object code of a \fB\&.hlsl\fP |
| source file. |
| .SS VS_SHADER_TYPE |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Set the Visual Studio shader type of a \fB\&.hlsl\fP source file. |
| .SS VS_SHADER_VARIABLE_NAME |
| .sp |
| New in version 3.10. |
| |
| .sp |
| Set name of variable in header file containing object code of a \fB\&.hlsl\fP |
| source file. |
| .SS VS_TOOL_OVERRIDE |
| .sp |
| New in version 3.7. |
| |
| .sp |
| Override the default Visual Studio tool that will be applied to the source file |
| with a new tool not based on the extension of the file. |
| .SS VS_XAML_TYPE |
| .sp |
| New in version 3.3. |
| |
| .sp |
| Mark a Extensible Application Markup Language (XAML) source file |
| as a different type than the default \fBPage\fP\&. |
| The most common usage would be to set the default \fBApp.xaml\fP file as |
| \fBApplicationDefinition\fP\&. |
| .SS WRAP_EXCLUDE |
| .sp |
| Exclude this source file from any code wrapping techniques. |
| .sp |
| Some packages can wrap source files into alternate languages to |
| provide additional functionality. |
| .sp |
| For example, C++ code can be wrapped into Java or Python, using SWIG. |
| If \fBWRAP_EXCLUDE\fP is set to \fBTrue\fP, that indicates that this |
| source file should not be wrapped. |
| .SS XCODE_EXPLICIT_FILE_TYPE |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Set the \fBXcode\fP \fBexplicitFileType\fP attribute on its reference to a |
| source file. CMake computes a default based on file extension but |
| can be told explicitly with this property. |
| .sp |
| See also \fBXCODE_LAST_KNOWN_FILE_TYPE\fP\&. |
| .SS XCODE_FILE_ATTRIBUTES |
| .sp |
| New in version 3.7. |
| |
| .sp |
| Add values to the \fBXcode\fP \fBATTRIBUTES\fP setting on its reference to a |
| source file. Among other things, this can be used to set the role on |
| a \fB\&.mig\fP file: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_source_files_properties(defs.mig |
| PROPERTIES |
| XCODE_FILE_ATTRIBUTES "Client;Server" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS XCODE_LAST_KNOWN_FILE_TYPE |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Set the \fBXcode\fP \fBlastKnownFileType\fP attribute on its reference to |
| a source file. CMake computes a default based on file extension but |
| can be told explicitly with this property. |
| .sp |
| See also \fBXCODE_EXPLICIT_FILE_TYPE\fP, which is preferred |
| over this property if set. |
| .SH PROPERTIES ON CACHE ENTRIES |
| .SS ADVANCED |
| .sp |
| True if entry should be hidden by default in GUIs. |
| .sp |
| This is a boolean value indicating whether the entry is considered |
| interesting only for advanced configuration. The \fBmark_as_advanced()\fP |
| command modifies this property. |
| .SS HELPSTRING |
| .sp |
| Help associated with entry in GUIs. |
| .sp |
| This string summarizes the purpose of an entry to help users set it |
| through a CMake GUI. |
| .SS MODIFIED |
| .sp |
| Internal management property. Do not set or get. |
| .sp |
| This is an internal cache entry property managed by CMake to track |
| interactive user modification of entries. Ignore it. |
| .SS STRINGS |
| .sp |
| Enumerate possible \fBSTRING\fP entry values for GUI selection. |
| .sp |
| For cache entries with type \fBSTRING\fP, this enumerates a set of values. |
| CMake GUIs may use this to provide a selection widget instead of a |
| generic string entry field. This is for convenience only. CMake does |
| not enforce that the value matches one of those listed. |
| .SS TYPE |
| .sp |
| Widget type for entry in GUIs. |
| .sp |
| Cache entry values are always strings, but CMake GUIs present widgets |
| to help users set values. The GUIs use this property as a hint to |
| determine the widget type. Valid \fBTYPE\fP values are: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| BOOL = Boolean ON/OFF value. |
| PATH = Path to a directory. |
| FILEPATH = Path to a file. |
| STRING = Generic string value. |
| INTERNAL = Do not present in GUI at all. |
| STATIC = Value managed by CMake, do not change. |
| UNINITIALIZED = Type not yet specified. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Generally the \fBTYPE\fP of a cache entry should be set by the command which |
| creates it ( \fBset()\fP, \fBoption()\fP, \fBfind_library()\fP, etc.). |
| .SS VALUE |
| .sp |
| Value of a cache entry. |
| .sp |
| This property maps to the actual value of a cache entry. Setting this |
| property always sets the value without checking, so use with care. |
| .SH PROPERTIES ON INSTALLED FILES |
| .SS CPACK_DESKTOP_SHORTCUTS |
| .sp |
| New in version 3.3. |
| |
| .sp |
| Species a list of shortcut names that should be created on the \fIDesktop\fP |
| for this file. |
| .sp |
| The property is currently only supported by the \fBCPack WIX Generator\fP\&. |
| .SS CPACK_NEVER_OVERWRITE |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Request that this file not be overwritten on install or reinstall. |
| .sp |
| The property is currently only supported by the \fBCPack WIX Generator\fP\&. |
| .SS CPACK_PERMANENT |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Request that this file not be removed on uninstall. |
| .sp |
| The property is currently only supported by the \fBCPack WIX Generator\fP\&. |
| .SS CPACK_START_MENU_SHORTCUTS |
| .sp |
| New in version 3.3. |
| |
| .sp |
| Species a list of shortcut names that should be created in the \fIStart Menu\fP |
| for this file. |
| .sp |
| The property is currently only supported by the \fBCPack WIX Generator\fP\&. |
| .SS CPACK_STARTUP_SHORTCUTS |
| .sp |
| New in version 3.3. |
| |
| .sp |
| Species a list of shortcut names that should be created in the \fIStartup\fP folder |
| for this file. |
| .sp |
| The property is currently only supported by the \fBCPack WIX Generator\fP\&. |
| .SS CPACK_WIX_ACL |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Specifies access permissions for files or directories |
| installed by a WiX installer. |
| .sp |
| The property can contain multiple list entries, |
| each of which has to match the following format. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| <user>[@<domain>]=<permission>[,<permission>] |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fB<user>\fP and \fB<domain>\fP specify the windows user and domain for which the |
| \fB<Permission>\fP element should be generated. |
| .sp |
| \fB<permission>\fP is any of the YesNoType attributes listed here: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| http://wixtoolset.org/documentation/manual/v3/xsd/wix/permission.html |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The property is currently only supported by the \fBCPack WIX Generator\fP\&. |
| .SH DEPRECATED PROPERTIES ON DIRECTORIES |
| .SS ADDITIONAL_MAKE_CLEAN_FILES |
| .sp |
| Deprecated since version 3.15: Use \fBADDITIONAL_CLEAN_FILES\fP instead. |
| |
| .sp |
| Additional files to remove during the clean stage. |
| .sp |
| A ;\-list of files that will be removed as a |
| part of the \fBmake clean\fP target. |
| .sp |
| Arguments to \fI\%ADDITIONAL_MAKE_CLEAN_FILES\fP may use |
| \fBgenerator expressions\fP\&. |
| .sp |
| This property only works for the Makefile generators. |
| It is ignored on other generators. |
| .SS COMPILE_DEFINITIONS_<CONFIG> |
| .sp |
| Ignored. See CMake Policy \fBCMP0043\fP\&. |
| .sp |
| Per\-configuration preprocessor definitions in a directory. |
| .sp |
| This is the configuration\-specific version of \fBCOMPILE_DEFINITIONS\fP |
| where \fB<CONFIG>\fP is an upper\-case name (ex. \fBCOMPILE_DEFINITIONS_DEBUG\fP). |
| .sp |
| This property will be initialized in each directory by its value in |
| the directory\(aqs parent. |
| .sp |
| Contents of \fBCOMPILE_DEFINITIONS_<CONFIG>\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .sp |
| Generator expressions should be preferred instead of setting this property. |
| .SS TEST_INCLUDE_FILE |
| .sp |
| Deprecated. Use \fBTEST_INCLUDE_FILES\fP instead. |
| .sp |
| A cmake file that will be included when ctest is run. |
| .sp |
| If you specify \fBTEST_INCLUDE_FILE\fP, that file will be included and |
| processed when ctest is run on the directory. |
| .SH DEPRECATED PROPERTIES ON TARGETS |
| .SS COMPILE_DEFINITIONS_<CONFIG> |
| .sp |
| Ignored. See CMake Policy \fBCMP0043\fP\&. |
| .sp |
| Per\-configuration preprocessor definitions on a target. |
| .sp |
| This is the configuration\-specific version of \fBCOMPILE_DEFINITIONS\fP |
| where \fB<CONFIG>\fP is an upper\-case name (ex. \fBCOMPILE_DEFINITIONS_DEBUG\fP). |
| .sp |
| Contents of \fBCOMPILE_DEFINITIONS_<CONFIG>\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .sp |
| Generator expressions should be preferred instead of setting this property. |
| .SS POST_INSTALL_SCRIPT |
| .sp |
| Deprecated install support. |
| .sp |
| The \fBPRE_INSTALL_SCRIPT\fP and \fBPOST_INSTALL_SCRIPT\fP properties are |
| the old way to specify CMake scripts to run before and after installing a |
| target. They are used only when the old \fBINSTALL_TARGETS\fP command is |
| used to install the target. Use the \fBinstall()\fP command instead. |
| .SS PRE_INSTALL_SCRIPT |
| .sp |
| Deprecated install support. |
| .sp |
| The \fBPRE_INSTALL_SCRIPT\fP and \fBPOST_INSTALL_SCRIPT\fP properties are |
| the old way to specify CMake scripts to run before and after installing a |
| target. They are used only when the old \fBINSTALL_TARGETS\fP command is |
| used to install the target. Use the \fBinstall()\fP command instead. |
| .SH DEPRECATED PROPERTIES ON SOURCE FILES |
| .SS COMPILE_DEFINITIONS_<CONFIG> |
| .sp |
| Ignored. See CMake Policy \fBCMP0043\fP\&. |
| .sp |
| Per\-configuration preprocessor definitions on a source file. |
| .sp |
| This is the configuration\-specific version of \fBCOMPILE_DEFINITIONS\fP\&. |
| Note that \fBXcode\fP does not support per\-configuration source |
| file flags so this property will be ignored by the \fBXcode\fP generator. |
| .SH COPYRIGHT |
| 2000-2022 Kitware, Inc. and Contributors |
| .\" Generated by docutils manpage writer. |
| . |