CMAKE-PROPERTIES(7)

🎀 `cmake-properties` 🎀

hiii so this is the CMake Properties Reference — that's CMAKE-PROPERTIES(7) if you're being formal about it ✨ it's the big index of every property CMake knows about, and this part is all about the global ones, iykyk 💅

💖 NAME 💖

cmake-properties — CMake Properties Reference 🫶

🌈 PROPERTIES OF GLOBAL SCOPE 🌈

🦋 `ALLOW_DUPLICATE_CUSTOM_TARGETS` 🦋

Let duplicate custom targets exist, bestie. Normally CMake is so strict and requires every target built in a project to have a globally unique logical name (see policy CMP0002 😤). Why? Because it needs to generate meaningful project file names in Xcode and Visual Studio Generators IDE generators, and it also lets target names be referenced unambiguously. main character requirements, honestly.

Makefile generators can handle duplicate add_custom_target() names though. So if your project only cares about Makefile Generators and does not wish to support Xcode or Visual Studio Generators IDE generators, you may set this property to True and allow duplicate custom targets. The property lets multiple add_custom_target() command calls in different directories specify the same target name 💖

⚠️ but bestie, be careful: setting this property will cause non-Makefile generators to produce an error and refuse to generate the project. not a vibe 💀

🌸 `AUTOGEN_SOURCE_GROUP` 🌸

added in version 3.9 ✨

Name of the source_group() for AUTOMOC, AUTORCC and AUTOUIC generated files.

So here's the thing: files generated by AUTOMOC, AUTORCC and AUTOUIC are not always known at configure time, and therefore can't be passed to source_group() 😭 AUTOGEN_SOURCE_GROUP can be used instead to generate or select a source group for AUTOMOC, AUTORCC and AUTOUIC generated files 🎀

For AUTOMOC, AUTORCC and AUTOUIC specific overrides, see AUTOMOC_SOURCE_GROUP, AUTORCC_SOURCE_GROUP and AUTOUIC_SOURCE_GROUP respectively 👑

🧚 `AUTOGEN_TARGETS_FOLDER` 🧚

Name of FOLDER for *_autogen targets that are added automatically by CMake for targets for which AUTOMOC is enabled.

If it's not set, CMake uses the FOLDER property of the parent target as a default value for this property. See also the documentation for the FOLDER target property and the AUTOMOC target property 💫

🍓 `AUTOMOC_SOURCE_GROUP` 🍓

added in version 3.9 ✨

Name of the source_group() for AUTOMOC generated files.

When set, this is used instead of AUTOGEN_SOURCE_GROUP for files generated by AUTOMOC. so it's the more specific one, it wins 💅

💜 `AUTOMOC_TARGETS_FOLDER` 💜

Name of FOLDER for *_autogen targets that are added automatically by CMake for targets for which AUTOMOC is enabled.

🚨 this property is obsolete. Use AUTOGEN_TARGETS_FOLDER instead, fr fr.

🔥 `AUTORCC_SOURCE_GROUP` 🔥

added in version 3.9 ✨

Name of the source_group() for AUTORCC generated files.

When set, this is used instead of AUTOGEN_SOURCE_GROUP for files generated by AUTORCC. she's specific and she knows it 🫶

⭐ `AUTOUIC_SOURCE_GROUP` ⭐

added in version 3.21 ✨

Name of the source_group() for AUTOUIC generated files.

When set, this is used instead of AUTOGEN_SOURCE_GROUP for files generated by AUTOUIC 💖

🌊 `CMAKE_C_KNOWN_FEATURES` 🌊

added in version 3.1 ✨

List of C features known to this version of CMake.

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 CMAKE_C_COMPILE_FEATURES variable 👑

The features listed here may be used with the target_compile_features() command. See the cmake-compile-features(7) manual for information on compile features and a list of supported compilers 📚

The features known to this version of CMake are listed below 💫

💅 High level meta features indicating C standard support 💅

added in version 3.8 ✨

c_std_90 — compiler mode is at least C 90.
c_std_99 — compiler mode is at least C 99.
c_std_11 — compiler mode is at least C 11.
c_std_17 — compiler mode is at least C 17. (added in version 3.21 ✨)
c_std_23 — compiler mode is at least C 23. (added in version 3.21 ✨)

📌 Note: if the compiler's default standard level is at least that of the requested feature, CMake may omit the -std= flag. The flag may still be added if the compiler's default extensions mode does not match the <LANG>_EXTENSIONS target property, or if the <LANG>_STANDARD target property is set. so like. it might show up anyway, don't @ me 😭

🌸 Low level individual compile features 🌸

c_function_prototypes — function prototypes, as defined in ISO/IEC 9899:1990.
c_restrict — the restrict keyword, as defined in ISO/IEC 9899:1999.
c_static_assert — static assert, as defined in ISO/IEC 9899:2011.
c_variadic_macros — variadic macros, as defined in ISO/IEC 9899:1999.

🦋 `CMAKE_CUDA_KNOWN_FEATURES` 🦋

added in version 3.17 ✨

List of CUDA features known to this version of CMake.

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 CMAKE_CUDA_COMPILE_FEATURES variable 👑

The features known to this version of CMake are:

cuda_std_03 — compiler mode is at least CUDA/C++ 03.
cuda_std_11 — compiler mode is at least CUDA/C++ 11.
cuda_std_14 — compiler mode is at least CUDA/C++ 14.
cuda_std_17 — compiler mode is at least CUDA/C++ 17.
cuda_std_20 — compiler mode is at least CUDA/C++ 20.
cuda_std_23 — compiler mode is at least CUDA/C++ 23. (added in version 3.20 ✨)
cuda_std_26 — compiler mode is at least CUDA/C++ 26. (added in version 3.30 ✨)

📌 Note: if the compiler's default standard level is at least that of the requested feature, CMake may omit the -std= flag. The flag may still be added if the compiler's default extensions mode does not match the <LANG>_EXTENSIONS target property, or if the <LANG>_STANDARD target property is set. same energy as before, it's giving déjà vu 💀

👑 `CMAKE_CXX_KNOWN_FEATURES` 👑

added in version 3.1 ✨

List of C++ features known to this version of CMake.

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 CMAKE_CXX_COMPILE_FEATURES variable 🫶

The features known to this version of CMake are listed below 💫

💖 High level meta features indicating C++ standard support 💖

added in version 3.8 ✨

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. (read that twice, bestie, the compiler might be lying a lil bit 🙈)

cxx_std_98 — compiler mode is at least C++ 98.
cxx_std_11 — compiler mode is at least C++ 11.
cxx_std_14 — compiler mode is at least C++ 14.
cxx_std_17 — compiler mode is at least C++ 17.
cxx_std_20 — compiler mode is at least C++ 20. (added in version 3.12 ✨)
cxx_std_23 — compiler mode is at least C++ 23. (added in version 3.20 ✨)
cxx_std_26 — compiler mode is at least C++ 26. (added in version 3.30 ✨)

📌 Note: if the compiler's default standard level is at least that of the requested feature, CMake may omit the -std= flag. The flag may still be added if the compiler's default extensions mode does not match the <LANG>_EXTENSIONS target property, or if the <LANG>_STANDARD target property is set. yes it's the same note again, it applies here too 😌

🧚 Low level individual compile features 🧚

okay history lesson: for C++ 11 and C++ 14, compilers were sometimes slow to implement certain language features 😭 so 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. periodt.

See the cmake-compile-features(7) manual for further discussion of the use of individual compile features 📖

✨ Individual features from C++ 98 ✨

cxx_template_template_parameters — template template parameters, as defined in ISO/IEC 14882:1998.

✨ Individual features from C++ 11 ✨

cxx_alias_templates — template aliases, as defined in N2258.
cxx_alignas — alignment control alignas, as defined in N2341.
cxx_alignof — alignment control alignof, as defined in N2341.
cxx_attributes — generic attributes, as defined in N2761.

(still rolling through the C++11 feature list — we do not skip a single one, bestie 💅)

cxx_auto_type — automatic type deduction, exactly as N1984 spells it out (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1984.pdf). let the compiler do the guessing for once ✨
cxx_constexpr — constant expressions, defined in N2235 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2235.pdf).
cxx_decltype_incomplete_return_types — decltype on incomplete return types, from N3276 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3276.pdf).
cxx_decltype — decltype, per N2343 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2343.pdf).
cxx_default_function_template_args — default template arguments for function templates, as defined in DR226 (https://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#226)
cxx_defaulted_functions — defaulted functions, per N2346 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm).
cxx_defaulted_move_initializers — defaulted move initializers, N3053 said it first (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3053.html).
cxx_delegating_constructors — delegating constructors, N1986 core (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1986.pdf).
cxx_deleted_functions — deleted functions, as in N2346 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm).
cxx_enum_forward_declarations — enum forward declarations, N2764 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2764.pdf).
cxx_explicit_conversions — explicit conversion operators, N2437 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2437.pdf).
cxx_extended_friend_declarations — extended friend declarations, N1791 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1791.pdf).
cxx_extern_templates — extern templates, N1987 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1987.htm).
cxx_final — the override control final keyword, defined across N2928 (https://www.open-std.org/JTC1/SC22/WG21/docs/papers/2009/n2928.htm), N3206 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3206.htm) and N3272 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3272.htm). three papers, one iconic little word 👑
cxx_func_identifier — the predefined __func__ identifier, N2340 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2340.htm).
cxx_generalized_initializers — initializer lists, N2672 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2672.htm).
cxx_inheriting_constructors — inheriting constructors, N2540 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2540.htm).
cxx_inline_namespaces — inline namespaces, N2535 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2535.htm).
cxx_lambdas — lambda functions, N2927 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2927.pdf). the moment C++ got main character energy, fr fr 🎀
cxx_local_type_template_args — local and unnamed types used as template arguments, N2657 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2657.htm).
cxx_long_long_type — the long long type, N1811 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1811.pdf).
cxx_noexcept — exception specifications, N3050 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3050.html).
cxx_nonstatic_member_init — non-static data member initialization, N2756 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2756.htm).
cxx_nullptr — the null pointer, N2431 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2431.pdf). goodbye NULL, you will not be missed 😌
cxx_override — the override control override keyword, again from N2928 (https://www.open-std.org/JTC1/SC22/WG21/docs/papers/2009/n2928.htm), N3206 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3206.htm) and N3272 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3272.htm).
cxx_range_for — range-based for, N2930 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2930.html). the glow-up your loops deserved ✨
cxx_raw_string_literals — raw string literals, N2442 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2442.htm).
cxx_reference_qualified_functions — reference qualified functions, N2439 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2439.htm).
cxx_right_angle_brackets — right angle bracket parsing, N1757 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1757.html). no more > > drama, we love to see it 💀
cxx_rvalue_references — r-value references, N2118 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2118.html).
cxx_sizeof_member — sizeof on non-static data members, N2253 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2253.html).
cxx_static_assert — static assert, N1720 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1720.html).
cxx_strong_enums — strongly typed enums, N2347 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2347.pdf).
cxx_thread_local — thread-local variables, N2659 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2659.htm).
cxx_trailing_return_types — automatic function return type, N2541 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2541.htm).
cxx_unicode_literals — Unicode string literals, N2442 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2442.htm).
cxx_uniform_initialization — uniform initialization, N2640 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2640.pdf).
cxx_unrestricted_unions — unrestricted unions, N2544 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2544.pdf).
cxx_user_literals — user-defined literals, N2765 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2765.pdf).
cxx_variadic_macros — variadic macros, N1653 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1653.htm).
cxx_variadic_templates — variadic templates, N2242 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2242.pdf).

🦋 Individual features from C++ 14 🦋

cxx_aggregate_default_initializers — aggregate default initializers, N3605 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3605.html).
cxx_attribute_deprecated — the [[deprecated]] attribute, N3760 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3760.html).
cxx_binary_literals — binary literals, N3472 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3472.pdf).
cxx_contextual_conversions — contextual conversions, N3323 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3323.pdf).
cxx_decltype_auto — decltype(auto) semantics, N3638 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3638.html).
cxx_digit_separators — digit separators, N3781 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3781.pdf). 1'000'000 my beloved 🫶
cxx_generic_lambdas — generic lambdas, N3649 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3649.html).
cxx_lambda_init_captures — initialized lambda captures, N3648 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3648.html).
cxx_relaxed_constexpr — relaxed constexpr, N3652 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3652.html).
cxx_return_type_deduction — return type deduction on normal functions, N3386 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3386.html).
cxx_variable_templates — variable templates, N3651 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3651.pdf).

🌈 `CMAKE_HIP_KNOWN_FEATURES` 🌈

Added in version 3.30. (baby property, new new ✨)

This is the list of HIP features that this version of CMake actually knows about — like, the roster it's carrying.

Here's the tea: the features listed in this global property may be known to be available to the HIP compiler. And if a feature is available with the HIP compiler, it'll show up listed in the CMAKE_HIP_COMPILE_FEATURES variable. iykyk 💅

You can use the features listed here with the target_compile_features() command. Want the full scoop on compile features and which compilers are supported? Go read cmake-compile-features(7).

The features known to this CMake version are:

hip_std_98 — compiler mode is at least HIP/C++ 98.
hip_std_11 — compiler mode is at least HIP/C++ 11.
hip_std_14 — compiler mode is at least HIP/C++ 14.
hip_std_17 — compiler mode is at least HIP/C++ 17.
hip_std_20 — compiler mode is at least HIP/C++ 20.
hip_std_23 — compiler mode is at least HIP/C++ 23.
hip_std_26 — Added in version 3.30. compiler mode is at least HIP/C++ 26.

Note: if the compiler's default standard level is already at least whatever you requested, CMake might just... not bother adding the -std= flag. 🙈 It can still add it though, either when the compiler's default extensions mode doesn't match the <LANG>_EXTENSIONS target property, or when the <LANG>_STANDARD target property is set. so don't come for CMake when the flag ghosts you.

🧚 `CMAKE_ROLE` 🧚

Added in version 3.14.

This one tells you what mode the currently running script is in — like checking which group chat you accidentally posted in. 💀 It can be one of several values:

PROJECT — running in project mode (processing a CMakeLists.txt file). the classic. the main character.
SCRIPT — running in cmake -P script mode.
FIND_PACKAGE — running in cmake --find-package mode.
CTEST — running in CTest script mode.
CPACK — running in CPack.

👑 See Also 👑

The CMAKE_SCRIPT_MODE_FILE variable. go peek, it's right there 🫶

💅 DEBUG_CONFIGURATIONS

okay so this property tells CMake which Build Configurations are, like, the debugging ones ✨

The value has to be a semicolon-separated list of build configuration names. rn this property is used by exactly one command — target_link_libraries() — and nowhere else. but like, additional uses may be defined in the future, so don't get too comfortable 👀

Where you set it matters, bestie: this property must be set at the top level of the project and before the first target_link_libraries() invocation. And if any entry in that list doesn't match a valid configuration for the project? behavior is undefined 💀 no cap, don't do that.

By default, this property is not set.

Examples

This one adds a custom configuration to the non-optimized debug configs while preserving whatever's already there. And if your project uses the default Debug configuration, it should be included too 🫶

set_property(GLOBAL APPEND PROPERTY DEBUG_CONFIGURATIONS Debug CustomBuild)

🎀 DISABLED_FEATURES

List of features which are disabled during the CMake run.

So by default this list contains the names of all the packages that were not found — CMake figures that out using the <NAME>_FOUND variables. little detail tho: packages that were searched QUIET are not listed 🙈

A project can also add its own features to this list. And this property is what the macros in the FeatureSummary module actually use 🌸

🦋 ECLIPSE_EXTRA_CPROJECT_CONTENTS

Added in version 3.12.

Extra contents to be inserted into the generated Eclipse cproject file.

The cproject file is the one that defines the CDT-specific information. Some third party IDE's are based on Eclipse, and they tack on their own extra info specific to that IDE. Through this property you can add that additional content into the generated project 💫 It's expected to contain valid XML, so like... actually make it valid, please.

Also see the ECLIPSE_EXTRA_NATURES property 👑

🧚 ECLIPSE_EXTRA_NATURES

List of natures to add to the generated Eclipse project file.

Eclipse projects specify language plugins by using natures. This property should be set to the unique identifier for a nature — and that identifier looks like a Java package name, if you were wondering 🌈

Also see the ECLIPSE_EXTRA_CPROJECT_CONTENTS property 💖

⭐ ENABLED_FEATURES

List of features which are enabled during the CMake run.

Same vibe as its disabled sibling: by default it contains the names of all packages that were found, determined using the <NAME>_FOUND variables. Packages searched QUIET are not listed 🍓 A project can add its own features to this list too, and the macros in the FeatureSummary module use this property 💅

👑 ENABLED_LANGUAGES

Read-only property that contains the list of currently enabled languages.

Set to list of currently enabled languages. that's it, that's the whole thing, she's simple and she's iconic ✨

🔥 FIND_LIBRARY_USE_LIB32_PATHS

Added in version 3.7.

Whether the find_library() command should automatically search lib32 directories.

FIND_LIBRARY_USE_LIB32_PATHS is a boolean specifying whether find_library() should automatically search the lib32 variant of directories called lib in the search path when building 32-bit binaries 💪

See also the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable.

💜 FIND_LIBRARY_USE_LIB64_PATHS

Whether find_library() should automatically search lib64 directories.

FIND_LIBRARY_USE_LIB64_PATHS is a boolean specifying whether find_library() should automatically search the lib64 variant of directories called lib in the search path when building 64-bit binaries 🌟

See also the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable.

🌸 FIND_LIBRARY_USE_LIBX32_PATHS

Added in version 3.9.

Whether the find_library() command should automatically search libx32 directories.

FIND_LIBRARY_USE_LIBX32_PATHS is a boolean specifying whether find_library() should automatically search the libx32 variant of directories called lib in the search path when building x32-abi binaries 🦋

See also the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable.

🐚 FIND_LIBRARY_USE_OPENBSD_VERSIONING

Whether find_library() should find OpenBSD-style shared libraries.

This property is a boolean specifying whether the find_library() command should find shared libraries with the OpenBSD-style versioned extension: .so.<major>.<minor> — yes with the literal angle brackets, it's a pattern, not a number, don't come for me 😭

The property is set to true on OpenBSD and false on other platforms. slay for platform-specific defaults 🫶

🌈 GENERATOR_IS_MULTI_CONFIG

Added in version 3.9.

Read-only property that is true on multi-configuration generators.

True when you're using a multi-configuration generator such as:

Ninja Multi-Config
Visual Studio Generators
Xcode

Multi-config generators use CMAKE_CONFIGURATION_TYPES as the set of configurations and straight up ignore CMAKE_BUILD_TYPE 💀 that's the whole vibe check right there.

🩷 GLOBAL_DEPENDS_DEBUG_MODE

Enable global target dependency graph debug mode.

CMake automatically analyzes the global inter-target dependency graph at the beginning of native build system generation. This property makes it display all the details of that analysis to stderr — so if you ever wanted to watch CMake think out loud, this is your moment 👀✨

🎯 GLOBAL_DEPENDS_NO_CYCLES

Disallow global target dependency graph cycles.

Again: CMake automatically analyzes the global inter-target dependency graph at the beginning of native build system generation. By default 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. no cycles. none. zero. periodt 💅

🧵 IN_TRY_COMPILE

Read-only property that is true during a try-compile configuration.

True when building a project inside a try_compile() or try_run() command. it's giving "are we in the test kitchen rn" energy 🍳

🚀 INSTALL_PARALLEL

Added in version 3.30.

Enables the parallel installation option for a project. The install code for each subdirectory added with add_subdirectory can run independently 🔥

When using the Ninja Generators, enabling this property causes install/local targets to have the console pool disabled, allowing them to run concurrently ✨

This property also provides the target install/parallel, which has an explicit dependency on the install/local target for each subdirectory.

Added in version 3.31. When this property is enabled, cmake --install can be given the -j <jobs> or --parallel <jobs> option to specify a maximum number of jobs. The CMAKE_INSTALL_PARALLEL_LEVEL environment variable specifies a default parallel level if this option is not provided 👑

Real talk though — calls to install(CODE) or install(SCRIPT) might depend on actions performed by an earlier install() command in a different directory, like files that got installed or variable settings. If your project has that kind of order-dependent installation logic, parallel installation should not be enabled, so you avoid possible race conditions 😭 that's a genuine warning, not a vibe.

🧺 JOB_POOLS

Ninja only: List of available pools.

A pool is a named integer property, and it defines the maximum number of concurrent jobs which can be started by a rule assigned to the pool. The JOB_POOLS property is a semicolon-separated list of pairs using the syntax NAME=integer — and no, there's no space after the equality sign, don't try it 🙈

For instance:

set_property(GLOBAL PROPERTY JOB_POOLS two_jobs=2 ten_jobs=10)

Defined pools can be used at different levels, and honestly the flexibility ate:

Globally, by setting CMAKE_JOB_POOL_COMPILE and CMAKE_JOB_POOL_LINK.
Per target, by setting the target properties JOB_POOL_COMPILE and JOB_POOL_LINK.
Custom commands and custom targets can specify pools using the option JOB_POOL.
Per-source, by setting the source file property JOB_POOL_COMPILE, in case some specific source files require to override their global or target assigned pool.

Using a pool that is not defined by JOB_POOLS causes an error by ninja at build time 💀 so like, define your pools first, bestie.

If not set, this property uses the value of the CMAKE_JOB_POOLS variable.

Build targets provided by CMake that are meant for individual interactive use, such as install, are placed in the console pool automatically 🎀

📦 PACKAGES_FOUND

List of packages which were found during the CMake run.

Whether a package has been found is determined using the <NAME>_FOUND variables. short, sweet, found 🌸

🫙 PACKAGES_NOT_FOUND

List of packages which were not found during the CMake run.

Whether a package has been found is determined using the <NAME>_FOUND variables. same rule, sadder list 😭

🗂️ PREDEFINED_TARGETS_FOLDER

Name of FOLDER for targets that are added automatically by CMake.

If not set, CMake uses "CMakePredefinedTargets" as the 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 FOLDER target property 👑

🧬 PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE

Added in version 3.30.

When this global property is set to true, the CMAKE_PROJECT_TOP_LEVEL_INCLUDES variable is propagated into try_compile() calls that use the whole-project signature 🌈

Calls to the source file signature are not affected by this property — different signature, different rules, we don't mix them 🙅‍♀️

PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE is unset by default.

...okay and for dependency providers that you want enabled inside whole-project try_compile() calls? Set this global property to true right before or right after you register the provider. 💅 Real talk though: every file listed in CMAKE_PROJECT_TOP_LEVEL_INCLUDES has to be able to handle being included in those try_compile() calls, and making sure that actually works is the user's responsibility. Not ours. Yours. 🫶

`REPORT_UNDEFINED_PROPERTIES`

Set this and CMake will snitch on everything. 👀

If it's set to a filename, then when CMake runs it reports any properties or variables that were accessed but not defined into that filename. It's giving "mom, I made a list of everyone who didn't show up." 🎀

`RULE_LAUNCH_COMPILE`

Specifies a launcher for compile rules. 🔥

Note: this property is genuinely meant for internal use by ctest(1). Projects and developers, bestie, please use the <LANG>_COMPILER_LAUNCHER target properties or the associated CMAKE_<LANG>_COMPILER_LAUNCHER variables instead. 🙈

Makefile Generators and the Ninja generator prefix compiler commands with the given launcher command line. The whole point is to let launchers intercept build problems with high granularity. Other generators just ignore this property because their underlying build systems provide no hook to wrap individual commands with a launcher. Not their fault, no shade. 💀

`RULE_LAUNCH_CUSTOM`

Specifies a launcher for custom rules. ✨

Makefile Generators and the Ninja generator prefix custom commands with the given launcher command line. Again: high granularity build-problem interception. Again: other generators ignore this property because their underlying build systems provide no hook to wrap individual commands with a launcher.

`RULE_LAUNCH_LINK`

Specifies a launcher for link rules. 🦋

Note: internal use by ctest(1), periodt. Projects and developers should use the <LANG>_LINKER_LAUNCHER target properties or the associated CMAKE_<LANG>_LINKER_LAUNCHER variables instead. 💅

Makefile Generators and the Ninja generator prefix link and archive commands with the given launcher command line. Yes, same reason — launchers intercepting 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.

`RULE_MESSAGES`

Specifies whether to report a message for each make rule. 🌸

This one decides whether Makefile generators add a progress message describing what each build rule does. Not set? Default is ON. Set it to OFF to disable those granular messages and only report as each target completes — meant so scripted builds can dodge the build-time cost of detailed reports. 🧚

If a CMAKE_RULE_MESSAGES cache entry exists, its value initializes the value of this property.

Non-Makefile generators currently ignore this property. 💜

`TARGET_ARCHIVES_MAY_BE_SHARED_LIBS`

Set if shared libraries may be named like archives. 👑

On AIX shared libraries may be named lib<name>.a, and this property is set to true on such platforms.

`TARGET_MESSAGES`

Added in version 3.4. ⭐

Specifies whether to report the completion of each target.

So this property decides whether Makefile Generators should add a progress message describing that each target has been completed. If the property is not set, the default is ON. Set the property to OFF to disable target completion messages. 💤

The vibe here is reducing build output when little or no work needs to be done to bring the build tree up to date.

If a CMAKE_TARGET_MESSAGES cache entry exists, its value initializes the value of this property.

Non-Makefile generators currently ignore this property. 🫶

And ooh, see the counterpart property RULE_MESSAGES — that's the one for disabling everything except target completion messages. Iconic teamwork.

`TARGET_SUPPORTS_SHARED_LIBS`

Does the target platform support shared libraries? 🤔

TARGET_SUPPORTS_SHARED_LIBS is a boolean specifying whether the target platform supports shared libraries. Basically all current general purpose OSes do, bestie — the exceptions are usually embedded systems with no OS or special OSs. 😭

`USE_FOLDERS`

Controls whether to use the FOLDER target property to organize targets into folders. 🎀 The value of USE_FOLDERS at the end of the top level CMakeLists.txt file is what determines the behavior — end of file, that's the vibe check.

Changed in version 3.26: CMake treats this property as ON by default. See policy CMP0143. 🌈

Not all CMake generators support recording folder details for targets — the Xcode and Visual Studio generators are examples of ones that do. Similarly, not all IDEs support presenting targets using folder hierarchies, even if the CMake generator used provides the necessary information. 🙈

`XCODE_EMIT_EFFECTIVE_PLATFORM_NAME`

Added in version 3.8. 🦋

Control emission of EFFECTIVE_PLATFORM_NAME by the Xcode generator.

It's required for building the same target with multiple SDKs, and a common use case is the parallel use of the iphoneos and iphonesimulator SDKs. 🔥

There are three different states that control when the Xcode generator emits the EFFECTIVE_PLATFORM_NAME variable:

If set to ON it will always be emitted
If set to OFF it will never be emitted
If unset (the default) it will only be emitted when the project was configured for an embedded Xcode SDK like iOS, tvOS, visionOS, watchOS or any of the simulators

Note: when this behavior is enabled for generated Xcode projects, the EFFECTIVE_PLATFORM_NAME variable will leak into Generator expressions like TARGET_FILE and will render those mostly unusable. 💀 Genuinely. Be careful.

🌸 PROPERTIES ON DIRECTORIES 🌸

`ADDITIONAL_CLEAN_FILES`

Added in version 3.15. ✨

A semicolon-separated list of files or directories that get removed as part of the global clean target. It's 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. 💅

If an additional clean file is specific to a single target only, then the ADDITIONAL_CLEAN_FILES target property would usually be a better choice than this directory property. Just saying. 🫶

Relative paths are allowed and are interpreted relative to the current binary directory.

Contents of ADDITIONAL_CLEAN_FILES may use generator expressions. 🎀

This property only works for the Ninja and the Makefile generators — it is ignored by other generators. 😭

`BINARY_DIR`

Added in version 3.7. ⭐

This read-only directory property reports the absolute path to the binary directory corresponding to the source on which it is read.

`BUILDSYSTEM_TARGETS`

Added in version 3.7. 🌈

This read-only directory property contains a semicolon-separated list of buildsystem targets added in the directory by calls to the add_library(), add_executable(), and add_custom_target() commands. 📋

The list does not include any Imported Targets or Alias Targets, but it does include Interface Libraries. Each entry in the list is the logical name of a target, suitable to pass to the get_property() command TARGET option.

See also the IMPORTED_TARGETS directory property. 👑

`CACHE_VARIABLES`

List of cache variables available in the current directory. 🗂️

This read-only property specifies the list of CMake cache variables currently defined. It is intended for debugging purposes — a little peek behind the curtain, iykyk. 🙈

`CLEAN_NO_CUSTOM`

Set to true to tell Makefile Generators not to remove the outputs of custom commands for this directory during the make clean operation. 🧹

This is ignored on other generators because it is not possible to implement. No cap, just not possible. 💀

`CMAKE_CONFIGURE_DEPENDS`

Tells 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.

Specify files as a semicolon-separated list of paths. Relative paths are interpreted as relative to the current source directory. 🎀

`COMPILE_DEFINITIONS`

Preprocessor definitions for compiling a directory's sources. 💖

This property specifies the list of options given so far to the add_compile_definitions() (or add_definitions()) command.

The COMPILE_DEFINITIONS property may be set to a semicolon-separated list of preprocessor definitions using the syntax VAR or VAR=value. 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 will be initialized in each directory by its value in the directory's parent.

CMake will automatically drop some definitions that are not supported by the native build tool. 🫶

Added in version 3.26: any leading -D on an item will be removed. ✨

Okay so before we get into the actual limitations list, a little editorial note from the CMake girlies, and it's important:

⚠️ 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 doesn't 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:

# — 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.
^ < > \ " — broken in most Make tools on Windows.

CMake does not reject these values outright, because they do work in some cases. Use with caution — this is a main character set of characters, not a safe one. 🙈

Contents of COMPILE_DEFINITIONS may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions. See the cmake-buildsystem(7) manual for more on defining buildsystem properties.

The corresponding COMPILE_DEFINITIONS_<CONFIG> property may be set to specify per-configuration definitions. Generator expressions should be preferred instead of setting the alternative property. (Yes bestie, the alternative property is lowkey deprecated energy — prefer the generator expressions.)

`COMPILE_OPTIONS`

List of options to pass to the compiler. 🛠️

This property holds a semicolon-separated list of options given so far to the add_compile_options() command.

This property is used to initialize the COMPILE_OPTIONS target property when a target is created, which is used by the generators to set the options for the compiler. So it's giving handoff — directory collects, target inherits, generator ships it to the compiler.

Contents of COMPILE_OPTIONS may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions. See the cmake-buildsystem(7) manual for more on defining buildsystem properties.

`DEFINITIONS`

For CMake 2.4 compatibility only. Use COMPILE_DEFINITIONS instead. 👵 Literally a legacy relic, bestie — respect the ancestors but don't take advice from them.

This read-only property specifies the list of flags given so far to the add_definitions() command. It is intended for debugging purposes. Use the COMPILE_DEFINITIONS directory property instead.

This built-in read-only property does not exist if policy CMP0059 is set to NEW. So if you go looking for it and it's gone? That's not a glitch, that's the policy doing its thing.

`EXCLUDE_FROM_ALL`

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. make in the parent directory will not build targets in the subdirectory by default. This does not affect the "all" target of the subdirectory itself — running e.g. make inside the subdirectory will still build its targets. (She has her own life, okay? 🦋)

EXCLUDE_FROM_ALL is meant for when the subdirectory contains a separate part of the project that is useful, but not necessary — such as a set of examples, or e.g. an integrated 3rd party library. Typically the subdirectory should contain its own project() command invocation so that a full build system will be generated in the subdirectory (such as a Visual Studio IDE solution file). Note that inter-target dependencies supersede this exclusion. If a target built by the parent project depends on a target in the subdirectory, the dependee target will be included in the parent project build system to satisfy the dependency. No cap — the dependency graph does not care about your vibe check. 🔥

If the EXCLUDE_FROM_ALL argument is provided, it has the following effects:

Targets defined in the subdirectory or below will not be included in the ALL target of the parent directory. Those targets must be built explicitly by the user, or be a dependency of another target that will be built.
Targets defined in the subdirectory or below will be excluded from IDE project files.
Any install rules defined in the subdirectory or below will be ignored when installing the parent directory.

Note that these effects are not the same as those for the EXCLUDE_FROM_ALL target property. Same name, different creature, bestie — do not confuse them. 💀

`IMPLICIT_DEPENDS_INCLUDE_TRANSFORM`

Specify #include line transforms for dependencies in a directory. ✨

This property specifies rules to transform macro-like #include 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 A_MACRO(%)=value-with-% (the % must be literal). During dependency scanning, occurrences of A_MACRO(...) on #include lines will be replaced by the value given, with the macro argument substituted for %. For example, the entry

MYDIR(%)=<mydir/%>

will convert lines of the form

#include MYDIR(myheader.h)

#include <mydir/myheader.h>

allowing the dependency to be followed. It's giving glow-up for your include scanner. 🧚

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's parent.

`IMPORTED_TARGETS`

Added in version 3.21.

This read-only directory property contains a semicolon-separated list of Imported Targets added in the directory by calls to the add_library() and add_executable() commands. Each entry in the list is the logical name of a target, suitable to pass to the get_property() command TARGET option when called in the same directory. So it's the guest list, and get_property() is the bouncer. 🎀

See also the BUILDSYSTEM_TARGETS directory property.

`INCLUDE_DIRECTORIES`

List of preprocessor include file search directories. 🗂️

This property specifies the list of directories given so far to the include_directories() command.

This property is used to populate the INCLUDE_DIRECTORIES target property, which is used by the generators to set the include directories for the compiler.

In addition to accepting values from that command, values may be set directly on any directory using the set_property() command, and can be set on the current directory using the set_directory_properties() command. A directory gets its initial value from its parent directory if it has one. The initial value of the INCLUDE_DIRECTORIES target property comes from the value of this property. Both directory and target property values are adjusted by calls to the include_directories() command. Calls to set_property() or set_directory_properties(), however, will update the directory property value without updating target property values. Therefore direct property updates must be made before calls to add_executable() or add_library() for targets they are meant to affect. ⏰ Timing is literally everything here — set it first, then make your targets, or the targets will not have heard about it.

The target property values are used by the generators to set the include paths for the compiler.

Contents of INCLUDE_DIRECTORIES may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions. See the cmake-buildsystem(7) manual for more on defining buildsystem properties.

`INCLUDE_REGULAR_EXPRESSION`

Include file scanning regular expression. 🔍

This property specifies the regular expression used during dependency scanning to match include files that should be followed. See the include_regular_expression() command for a high-level interface to set this property. (Nice of them to give you a friendly button instead of making you regex it up by hand, honestly.)

`LABELS`

Added in version 3.10.

Specify a list of text labels associated with a directory and all of its subdirectories. This is equivalent to setting the LABELS target property and the LABELS test property on all targets and tests in the current directory and subdirectories. Note: Launchers must enabled to propagate labels to targets. 👑 (Yes, that's how the original says it — "must enabled" — we keep it exactly as-is, bestie. Character for character.)

The CMAKE_DIRECTORY_LABELS variable can be used to initialize this property.

The list is reported in dashboard submissions. So your labels are literally going on the group chat that is the CDash dashboard. 💅

`LINK_DIRECTORIES`

List of linker search directories. 🔗

This property holds a semicolon-separated list of directories and is typically populated using the link_directories() command. It gets its initial value from its parent directory, if it has one. Family inheritance, but for linker flags. 🫶

The directory property is used to initialize the LINK_DIRECTORIES target property when a target is created. That target property is used by the generators to set the library search directories for the linker.

Contents of LINK_DIRECTORIES may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions. See the cmake-buildsystem(7) manual for more on defining buildsystem properties.

`LINK_OPTIONS`

Added in version 3.13.

List of options to use for the link step of shared library, module and executable targets, plus the device link step too. 👑

This property holds a semicolon-separated list of options given so far to the add_link_options() command — like, everything you've fed it up to this point, all queued up. 💅

It's used to initialize the LINK_OPTIONS target property when a target is created, and the generators use that to set the options for the compiler. ✨

Contents of LINK_OPTIONS may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions. See the cmake-buildsystem(7) manual for more on defining buildsystem properties. 🦋

`LISTFILE_STACK`

The current stack of listfiles being processed. 📚

This one is mainly useful when you're trying to debug errors in your CMake scripts — it's basically your call stack, bestie. It returns a list of what list files are currently being processed, in order. So if one listfile does an include() command, then that's effectively pushing the included listfile onto the stack. 🎀

`PARENT_DIRECTORY`

Source directory that added current subdirectory. 🫶

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. (Yes, empty. The main character has no parent. 😭)

`RULE_LAUNCH_COMPILE`

Specify a launcher for compile rules. 🔥

Note: This property is intended for internal use by ctest(1). Projects and developers should use the <LANG>_COMPILER_LAUNCHER target properties or the associated CMAKE_<LANG>_COMPILER_LAUNCHER variables instead.

See the global property RULE_LAUNCH_COMPILE of the same name for details. This overrides the global property for a directory. ✨

`RULE_LAUNCH_CUSTOM`

Specify a launcher for custom rules. 💜

See the global property of the same name for details. This overrides the global property for a directory.

`RULE_LAUNCH_LINK`

Specify a launcher for link rules. 🔗

Note: This property is intended for internal use by ctest(1). Projects and developers should use the <LANG>_LINKER_LAUNCHER target properties or the associated CMAKE_<LANG>_LINKER_LAUNCHER variables instead.

See the global property RULE_LAUNCH_LINK of the same name for details. This overrides the global property for a directory. 🌈

`SOURCE_DIR`

Added in version 3.7.

This read-only directory property reports the absolute path to the source directory on which it is read. Like, "where am I right now" but for your CMake project. 📍

`SUBDIRECTORIES`

Added in version 3.7.

This read-only directory property contains a semicolon-separated list of subdirectories processed so far by the add_subdirectory() or subdirs() commands. Each entry is the absolute path to the source directory (containing the CMakeLists.txt file). This is suitable to pass to the get_property() command DIRECTORY option. 🎀

Note: The subdirs() 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. (Lowkey rude, but okay. 💀)

`SYSTEM`

Added in version 3.25.

This directory property is used to initialize the SYSTEM target property for non-imported targets created in that directory. It is set to true by add_subdirectory() and FetchContent_Declare() when the SYSTEM option is given as an argument to those commands. 🦋

`TESTS`

Added in version 3.12.

List of tests. 🧪

This read-only property holds a semicolon-separated list of tests defined so far, in the current directory, by the add_test() command.

`TEST_INCLUDE_FILES`

Added in version 3.10.

This directory property specifies a list of CMake scripts to be included and processed when ctest runs on the directory. Use absolute paths, to avoid ambiguity. Script files are included in the specified order. 📝

TEST_INCLUDE_FILES scripts are processed when running ctest, not during the cmake configuration phase. These scripts should be written as if they were CTest dashboard scripts. It is common to generate such scripts dynamically since many variables and commands available during configuration are not accessible at test phase. 🌸

Examples

Setting this directory property to append one or more CMake scripts:

CMakeLists.txt

configure_file(script.cmake.in script.cmake)

set_property(
  DIRECTORY
  APPEND
  PROPERTY TEST_INCLUDE_FILES
    ${CMAKE_CURRENT_BINARY_DIR}/script.cmake
    ${CMAKE_CURRENT_SOURCE_DIR}/foo.cmake
    ${dir}/bar.cmake
)

script.cmake.in

execute_process(
  COMMAND "@CMAKE_COMMAND@" -E echo "script.cmake executed during CTest"
)

`VARIABLES`

List of variables defined in the current directory. 👑

This read-only property specifies the list of CMake variables currently defined. It is intended for debugging purposes.

`VS_GLOBAL_SECTION_POST_<section>`

Specify a postSolution global section in Visual Studio. 💅

Setting a property like this generates an entry of the following form in the solution file:

GlobalSection(<section>) = postSolution
  <contents based on property value>
EndGlobalSection

The property must be set to a semicolon-separated list of key=value 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. 🙈

This property only works for Visual Studio Generators; it is ignored on other generators. The property only applies when set on a directory whose CMakeLists.txt contains a project() command. 🎯

Note that CMake generates postSolution sections ExtensibilityGlobals and ExtensibilityAddIns by default. If you set the corresponding property, it will override the default section. For example, setting VS_GLOBAL_SECTION_POST_ExtensibilityGlobals will override the default contents of the ExtensibilityGlobals section, while keeping ExtensibilityAddIns on its default. However, CMake will always add a SolutionGuid to the ExtensibilityGlobals section if it is not specified explicitly. ⭐

`VS_GLOBAL_SECTION_PRE_<section>`

Specify a preSolution global section in Visual Studio. 🌟

Setting a property like this generates an entry of the following form in the solution file:

GlobalSection(<section>) = preSolution
  <contents based on property value>
EndGlobalSection

This property only works for Visual Studio Generators; it is ignored on other generators. The property only applies when set on a directory whose CMakeLists.txt contains a project() command. 💖

`VS_SOLUTION_ITEMS`

Added in version 4.0.

Specify solution level items included in the generated Visual Studio solution. 📁

The Visual Studio Generators create a .sln file for each directory whose CMakeLists.txt file calls the project() command. Append paths to this property in the same directory as the top-level project() command call (e.g. in the top-level CMakeLists.txt file) to specify files included in the corresponding solution file. 🎀

If a file specified in VS_SOLUTION_ITEMS matches a source_group() command call, the affected solution level items are placed in a hierarchy of solution level folders according to the name specified in that command. Otherwise the items are placed in a default solution level directory named Solution Items. This name matches the default directory name used by Visual Studio when attempting to add solution level items at the root of the solution. 💅

`VS_STARTUP_PROJECT`

Added in version 3.6.

Specify the default startup project in a Visual Studio solution. 🚀

The Visual Studio Generators create a .sln file for each directory whose CMakeLists.txt file calls the project() command. Set this property in the same directory as a project() command call (e.g. in the top-level CMakeLists.txt file) to specify the default startup project for the corresponding solution file. 👑

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. 🦋

If this property is not specified, then the ALL_BUILD project will be the default. (Yes, ALL_BUILD is that friend who's always the default. 😭)

✨ PROPERTIES ON TARGETS ✨

Omg okay, we're moving on from directories to targets — this is the section where it's all about the things you're actually building. Let's go. 🔥

`ADDITIONAL_CLEAN_FILES`

Added in version 3.15.

A semicolon-separated list of files or directories that will be removed as a part of the global clean 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). 🧹

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't target-specific, then the ADDITIONAL_CLEAN_FILES directory property may be the more appropriate property to use. 🎯

Relative paths are allowed and are interpreted relative to the current binary directory.

Contents of ADDITIONAL_CLEAN_FILES may use generator expressions.

This property only works for the Ninja and the Makefile generators. It is ignored by other generators. 💀

`AIX_EXPORT_ALL_SYMBOLS`

Added in version 3.17.

...so, bestie, on AIX CMake is very generous and automatically exports all the symbols from shared libraries, and also from executables that have the ENABLE_EXPORTS target property set. If you don't want that (and honestly, sometimes you don't 💅), just explicitly disable this boolean property and it'll export no symbols by default. In that case, the expectation is that your project will use other means to export the symbols it actually wants out there. Periodt.

This property gets initialized from the value of the CMAKE_AIX_EXPORT_ALL_SYMBOLS variable if that variable is set when a target is created. ✨

AIX_SHARED_LIBRARY_ARCHIVE

Added in version 3.31. 🎀

On AIX, this turns creation of a shared library archive on or off for a SHARED library target:

If enabled, the shared object .so file gets placed inside an archive .a file. This is the preferred convention on AIX. The shared object name in the archive encodes version information from the SOVERSION target property if it's set, and otherwise from the VERSION target property if that is set. 🦋
If disabled, you get a plain shared object .so file. This is consistent with other UNIX platforms.

This property defaults to CMAKE_AIX_SHARED_LIBRARY_ARCHIVE if that variable is set when a non-imported SHARED library target is created by add_library(). Imported targets must explicitly enable AIX_SHARED_LIBRARY_ARCHIVE if they import an AIX shared library archive. No cap, that's just how it is.

Changed in version 4.0: For a non-imported target, if this property is not set, the default is enabled. See policy CMP0182. 😭

In CMake 3.31, policy CMP0182 did not exist, so the default was disabled.

In CMake 3.30 and lower, AIX_SHARED_LIBRARY_ARCHIVE did not exist, so the default was disabled too. Rip to the old days 💀

ALIAS_GLOBAL

Added in version 3.18. ⭐

A read-only property that tells you whether an ALIAS target is globally visible. Iconic, honestly.

The boolean value of this property is TRUE for aliases to IMPORTED targets created with the GLOBAL option to add_executable() or add_library(), and FALSE otherwise. It's undefined for targets built within the project. 🙈

Note: Promoting an IMPORTED target from LOCAL to GLOBAL scope by changing the value of the IMPORTED_GLOBAL target property does not change the scope of local aliases. That's the rule, bestie, don't fight it.

ALIASED_TARGET

The name of the target aliased by this target. 🫶

If this is an Alias Target, this property contains the name of the target being aliased.

ANDROID_ANT_ADDITIONAL_OPTIONS

Added in version 3.4. 🌸

Sets the additional options for the Android Ant build system. This is a string value containing all the command line options for the Ant build. It's initialized by the value of the CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS variable if that's set when a target is created.

ANDROID_API

Added in version 3.1. ✨

When you're Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition, this property sets the Android target API version (e.g. 15). The version number must be a positive decimal integer. It's initialized by the value of the CMAKE_ANDROID_API variable if that's set when a target is created.

ANDROID_API_MIN

Added in version 3.2. 💜

Sets the Android MIN API version (e.g. 9). The version number must be a positive decimal integer. This property is initialized by the value of the CMAKE_ANDROID_API_MIN variable if it's set when a target is created. Native code builds using this API version. 🧚

ANDROID_ARCH

Added in version 3.4. 🎀

When you're Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition, this property sets the Android target architecture.

It's a string property that could be set to one of these values, and yes, you gotta pick from the list:

armv7-a: "ARMv7-A (armv7-a)"
armv7-a-hard: "ARMv7-A, hard-float ABI (armv7-a)"
arm64-v8a: "ARMv8-A, 64bit (arm64-v8a)"
x86: "x86 (x86)"
x86_64: "x86_64 (x86_64)"

This property is initialized by the value of the CMAKE_ANDROID_ARCH variable if it's set when a target is created. 💅

ANDROID_ASSETS_DIRECTORIES

Added in version 3.4. 🦋

Sets the Android assets directories to copy into the main assets folder before the build. It's a string property containing the directory paths separated by semicolons. This property is initialized by the value of the CMAKE_ANDROID_ASSETS_DIRECTORIES variable if it's set when a target is created.

ANDROID_GUI

Added in version 3.1. 🔥

When you're 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. Main character energy for your executable, lowkey.

When this property is set to true, the executable — when built for Android — will be created as an application package. It's initialized by the value of the CMAKE_ANDROID_GUI variable if it's set when a target is created.

Add the AndroidManifest.xml source file explicitly to the add_executable() command invocation to specify the root directory of the application package source. Don't forget it, bestie 🙈

ANDROID_JAR_DEPENDENCIES

Added in version 3.4. ⭐

Sets the Android property that specifies JAR dependencies. It's a string value property. This property is initialized by the value of the CMAKE_ANDROID_JAR_DEPENDENCIES variable if it's set when a target is created.

ANDROID_JAR_DIRECTORIES

Added in version 3.4. 🌈

Sets the Android property that specifies directories to search for the JAR libraries.

It's a string property that contains the directory paths separated by semicolons. This property is initialized by the value of the CMAKE_ANDROID_JAR_DIRECTORIES variable if it's set when a target is created.

Contents of ANDROID_JAR_DIRECTORIES may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions. 😌

ANDROID_JAVA_SOURCE_DIR

Added in version 3.4. 🎀

Sets the Android property that defines the Java source code root directories. It's a string property that contains the directory paths separated by semicolons. This property is initialized by the value of the CMAKE_ANDROID_JAVA_SOURCE_DIR variable if it's set when a target is created.

ANDROID_NATIVE_LIB_DEPENDENCIES

Added in version 3.4. 💖

Sets the Android property that specifies the .so dependencies. It's a string property.

This property is initialized by the value of the CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES variable if it's set when a target is created.

Contents of ANDROID_NATIVE_LIB_DEPENDENCIES may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions.

ANDROID_NATIVE_LIB_DIRECTORIES

Added in version 3.4. 🌸

Sets the Android property that specifies directories to search for the .so libraries.

It's a string property that contains the directory paths separated by semicolons.

This property is initialized by the value of the CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES variable if it's set when a target is created.

Contents of ANDROID_NATIVE_LIB_DIRECTORIES may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions. 🫶

ANDROID_PROCESS_MAX

Added in version 3.4. 🦋

Sets the Android property that defines the maximum number of parallel Android NDK compiler processes (e.g. 4). This property is initialized by the value of the CMAKE_ANDROID_PROCESS_MAX variable if it's set when a target is created.

ANDROID_PROGUARD

Added in version 3.4. ✨

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. Sneaky, but make it fashion 💅

This property is initialized by the value of the CMAKE_ANDROID_PROGUARD variable if it's set when a target is created.

ANDROID_PROGUARD_CONFIG_PATH

Added in version 3.4. 🧚

Sets the Android property that specifies the location of the ProGuard config file. Leave it empty to use the default one. It's a string property that contains the path to the ProGuard config file. This property is initialized by the value of the CMAKE_ANDROID_PROGUARD_CONFIG_PATH variable if it's set when a target is created.

ANDROID_SECURE_PROPS_PATH

Added in version 3.4. 🔥

Sets the Android property that states the location of the secure properties file. It's a string property that contains the file path. This property is initialized by the value of the CMAKE_ANDROID_SECURE_PROPS_PATH variable if it's set when a target is created.

ANDROID_SKIP_ANT_STEP

Added in version 3.4. 👑

Sets the Android property that defines whether or not to skip the Ant build step. It's a boolean property initialized by the value of the CMAKE_ANDROID_SKIP_ANT_STEP variable if it's set when a target is created.

ANDROID_STL_TYPE

Added in version 3.4. 🌈

When you're Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition, this property specifies the type of STL support for the project. It's a string property that could be set to one of the following values:

none — No C++ Support
system — Minimal C++ without STL
gabi++_static — GAbi++ Static
gabi++_shared — GAbi++ Shared
gnustl_static — GNU libstdc++ Static
gnustl_shared — GNU libstdc++ Shared
stlport_static — STLport Static
stlport_shared — STLport Shared

Pick your fighter, bestie 💖

Okay so this property gets its starting value from the CMAKE_ANDROID_STL_TYPE (<#variable:CMAKE_ANDROID_STL_TYPE>) variable if that variable is set when the target is created. ✨

🗂️ ARCHIVE_OUTPUT_DIRECTORY 🗂️

This is the output directory where CMake builds ARCHIVE (<#archive-output-artifacts>) target files. 💖

It literally specifies the directory into which archive target files should be built. The property value may use generator expressions (<#manual:cmake-generator-expressions(7)>). Multi-configuration generators — Visual Studio (<#visual-studio-generators>), Xcode (<#generator:Xcode>), and Ninja Multi-Config (<#generator:Ninja Multi-Config>) — append a per-configuration subdirectory to the specified directory unless a generator expression is used. Slay.

This property is initialized by the value of the CMAKE_ARCHIVE_OUTPUT_DIRECTORY (<#variable:CMAKE_ARCHIVE_OUTPUT_DIRECTORY>) variable if it is set when a target is created.

Note: On macOS, this property will be ignored for the linker import files (e.g. .tbd files, see ENABLE_EXPORTS (<#prop_tgt:ENABLE_EXPORTS>) property for details) when: - The FRAMEWORK (<#prop_tgt:FRAMEWORK>) is set, because the framework layout cannot be changed. - The Xcode (<#generator:Xcode>) generator is used, due to the limitations and constraints of the Xcode tool. In both cases, the linker import files will be generated in the same directory as the shared library.

See also the ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> (<#prop_tgt:ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>>) target property.

🎀 `ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>` 🎀

Per-configuration output directory for ARCHIVE (<#archive-output-artifacts>) target files. 💅

This is the per-configuration version of the ARCHIVE_OUTPUT_DIRECTORY (<#prop_tgt:ARCHIVE_OUTPUT_DIRECTORY>) target property, but multi-configuration generators (Visual Studio (<#visual-studio-generators>), Xcode (<#generator:Xcode>), Ninja Multi-Config (<#generator:Ninja Multi-Config>)) do NOT append a per-configuration subdirectory to the specified directory. This property is initialized by the value of the CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> (<#variable:CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>>) variable if it is set when a target is created.

Contents of ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> may use generator expressions (<#manual:cmake-generator-expressions(7)>). 🦋

🌸 ARCHIVE_OUTPUT_NAME 🌸

Output name for ARCHIVE (<#archive-output-artifacts>) target files. 💖

This property specifies the base name for archive target files. It overrides OUTPUT_NAME (<#prop_tgt:OUTPUT_NAME>) and OUTPUT_NAME_<CONFIG> (<#prop_tgt:OUTPUT_NAME_<CONFIG>>) properties.

Note: On macOS, this property will be ignored for the linker import files (e.g. .tbd files, see ENABLE_EXPORTS (<#prop_tgt:ENABLE_EXPORTS>) property for details) when: - The FRAMEWORK (<#prop_tgt:FRAMEWORK>) is set, because the framework layout cannot be changed. - The Xcode (<#generator:Xcode>) generator is used, due to the limitations and constraints of the Xcode tool. In both cases, the linker import files will be generated with the same name as the shared library.

See also the ARCHIVE_OUTPUT_NAME_<CONFIG> (<#prop_tgt:ARCHIVE_OUTPUT_NAME_<CONFIG>>) target property.

🎀 `ARCHIVE_OUTPUT_NAME_<CONFIG>` 🎀

Per-configuration output name for ARCHIVE (<#archive-output-artifacts>) target files. ✨

This is the configuration-specific version of the ARCHIVE_OUTPUT_NAME (<#prop_tgt:ARCHIVE_OUTPUT_NAME>) target property.

🧚 AUTOGEN_BETTER_GRAPH_MULTI_CONFIG 🧚

Added in version 3.29.

AUTOGEN_BETTER_GRAPH_MULTI_CONFIG is a boolean property that can be set on a target to have better dependency graph for multi-configuration generators. When this property is enabled, CMake will generate more per-config targets. Thus, the dependency graph will be more accurate for multi-configuration generators and some recompilations will be avoided. 🔥

If the Qt version is 6.8 or newer, this property is enabled by default. If the Qt version is older than 6.8, this property is disabled by default. Consult the Qt documentation to check if the property can be enabled for older Qt versions.

See the cmake-qt(7) (<#manual:cmake-qt(7)>) manual for more information on using CMake with Qt.

This property is initialized by the CMAKE_AUTOGEN_BETTER_GRAPH_MULTI_CONFIG (<#variable:CMAKE_AUTOGEN_BETTER_GRAPH_MULTI_CONFIG>) variable if it is set when a target is created.

🛠️ AUTOGEN_BUILD_DIR 🛠️

Added in version 3.9.

Directory where AUTOMOC (<#prop_tgt:AUTOMOC>), AUTOUIC (<#prop_tgt:AUTOUIC>) and AUTORCC (<#prop_tgt:AUTORCC>) generate files for the target. 💅

The directory is created on demand and automatically added to the ADDITIONAL_CLEAN_FILES (<#prop_tgt:ADDITIONAL_CLEAN_FILES>) target property.

When unset or empty the directory <dir>/<target-name>_autogen is used where <dir> is CMAKE_CURRENT_BINARY_DIR (<#variable:CMAKE_CURRENT_BINARY_DIR>) and <target-name> is NAME (<#prop_tgt:NAME>).

By default AUTOGEN_BUILD_DIR is unset.

See the cmake-qt(7) (<#manual:cmake-qt(7)>) manual for more information on using CMake with Qt.

📏 AUTOGEN_COMMAND_LINE_LENGTH_MAX 📏

Added in version 3.29.

Command line length limit for autogen targets, i.e. moc or uic, that triggers the use of response files on Windows instead of passing all arguments to the command line. 🫶

An empty (or unset) value sets the limit to 32000
A positive non zero integer value sets the exact command line length limit.

By default AUTOGEN_COMMAND_LINE_LENGTH_MAX is initialized from CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX (<#variable:CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX>).

See the cmake-qt(7) (<#manual:cmake-qt(7)>) manual for more information on using CMake with Qt.

🔗 AUTOGEN_ORIGIN_DEPENDS 🔗

Added in version 3.14.

Switch for forwarding origin target dependencies to the corresponding <ORIGIN>_autogen (<#origin-autogen>) target. 😭

Note: If the <ORIGIN>_autogen_timestamp_deps (<#origin-autogen-timestamp-deps>) target is created, origin target dependencies are forwarded to it instead of <ORIGIN>_autogen (<#origin-autogen>). When using the Visual Studio Generators (<#visual-studio-generators>), the moc and uic step may be part of the <ORIGIN> target itself, in which case they need no forwarding. See the cmake-qt(7) (<#manual:cmake-qt(7)>) manual for details.

Targets which have their AUTOMOC (<#prop_tgt:AUTOMOC>) or AUTOUIC (<#prop_tgt:AUTOUIC>) property ON have a corresponding <ORIGIN>_autogen (<#origin-autogen>) target which generates moc and uic files. As this <ORIGIN>_autogen (<#origin-autogen>) target is created at generate-time, it is not possible to define dependencies of it using e.g. add_dependencies() (<#command:add_dependencies>). Instead the AUTOGEN_ORIGIN_DEPENDS target property decides whether the origin target dependencies should be forwarded to the <ORIGIN>_autogen (<#origin-autogen>) target or not.

By default AUTOGEN_ORIGIN_DEPENDS is initialized from CMAKE_AUTOGEN_ORIGIN_DEPENDS (<#variable:CMAKE_AUTOGEN_ORIGIN_DEPENDS>) which is ON by default.

In total the dependencies of the <ORIGIN>_autogen (<#origin-autogen>) target are composed from:

forwarded origin target dependencies (enabled by default via AUTOGEN_ORIGIN_DEPENDS)
additional user defined dependencies from AUTOGEN_TARGET_DEPENDS (<#prop_tgt:AUTOGEN_TARGET_DEPENDS>)

See the cmake-qt(7) (<#manual:cmake-qt(7)>) manual for more information on using CMake with Qt.

Note: Disabling AUTOGEN_ORIGIN_DEPENDS is useful to avoid building of origin target dependencies when building the <ORIGIN>_autogen (<#origin-autogen>) target only. This is especially interesting when a global autogen target (<#variable:CMAKE_GLOBAL_AUTOGEN_TARGET>) is enabled. When the <ORIGIN>_autogen (<#origin-autogen>) target doesn't require all the origin target's dependencies, and AUTOGEN_ORIGIN_DEPENDS is disabled, it might be necessary to extend AUTOGEN_TARGET_DEPENDS (<#prop_tgt:AUTOGEN_TARGET_DEPENDS>) to add missing dependencies.

🧵 AUTOGEN_PARALLEL 🧵

Added in version 3.11.

Number of parallel moc or uic processes to start when using AUTOMOC (<#prop_tgt:AUTOMOC>) and AUTOUIC (<#prop_tgt:AUTOUIC>). 💀

The custom <ORIGIN>_autogen (<#origin-autogen>) target starts a number of threads. Each thread parses a source file and on demand starts a moc or uic process. AUTOGEN_PARALLEL controls how many parallel threads (and therefore moc or uic processes) are started.

An empty (or unset) value or the string AUTO sets the number of threads/processes to the number of physical CPUs on the host system.
A positive non zero integer value sets the exact thread/process count.
Otherwise a single thread/process is started.

By default AUTOGEN_PARALLEL is initialized from CMAKE_AUTOGEN_PARALLEL (<#variable:CMAKE_AUTOGEN_PARALLEL>).

See the cmake-qt(7) (<#manual:cmake-qt(7)>) manual for more information on using CMake with Qt.

🧩 AUTOGEN_TARGET_DEPENDS 🧩

Additional target dependencies of the corresponding <ORIGIN>_autogen (<#origin-autogen>) target. 🌈

Note: If the <ORIGIN>_autogen_timestamp_deps (<#origin-autogen-timestamp-deps>) target is created, additional target dependencies are added to it instead of the <ORIGIN>_autogen (<#origin-autogen>) target. When using the Visual Studio Generators (<#visual-studio-generators>), the moc and uic step may be part of the <ORIGIN> target itself, in which case the dependencies are added to <ORIGIN>. See the cmake-qt(7) (<#manual:cmake-qt(7)>) manual for details.

Targets which have their AUTOMOC (<#prop_tgt:AUTOMOC>) or AUTOUIC (<#prop_tgt:AUTOUIC>) property ON have a corresponding <ORIGIN>_autogen (<#origin-autogen>) target which generates moc and uic files. As this <ORIGIN>_autogen (<#origin-autogen>) target is created at generate-time, it is not possible to define dependencies of it using e.g. add_dependencies() (<#command:add_dependencies>). Instead the AUTOGEN_TARGET_DEPENDS target property can be set to a semicolon-separated list (<#cmake-language-lists>) of additional dependencies for the <ORIGIN>_autogen (<#origin-autogen>) target. Dependencies can be target names or file names.

In total, the dependencies of the <ORIGIN>_autogen (<#origin-autogen>) target are composed from:

forwarded origin target dependencies (enabled by default via AUTOGEN_ORIGIN_DEPENDS (<#prop_tgt:AUTOGEN_ORIGIN_DEPENDS>))
additional user defined dependencies from AUTOGEN_TARGET_DEPENDS

See the cmake-qt(7) (<#manual:cmake-qt(7)>) manual for more information on using CMake with Qt.

🌟 Use cases 🌟

If AUTOMOC (<#prop_tgt:AUTOMOC>) or AUTOUIC (<#prop_tgt:AUTOUIC>) depends on a file that is either

a GENERATED non C++ file (e.g. a GENERATED .json or .ui file) or
a GENERATED C++ file that isn't recognized by AUTOMOC and AUTOUIC because it's skipped by SKIP_AUTOMOC, SKIP_AUTOUIC, SKIP_AUTOGEN, or CMP0071 or
a file that isn't in the origin target's sources

…then bestie, it must be added to AUTOGEN_TARGET_DEPENDS. No cap. 🫶

✨ AUTOGEN_USE_SYSTEM_INCLUDE ✨

Added in version 3.27.

AUTOGEN_USE_SYSTEM_INCLUDE is a boolean property you can set on a target. It's the little switch that says the autogen target include directory should be added to the target as a system include directory or a normal include directory. 💅

If this property is not set, the autogen target include directory is added as a system include directory by default. See policy CMP0151. 👀

See the cmake-qt(7) manual for more information on using CMake with Qt. 🦋

This property is initialized by the CMAKE_AUTOGEN_USE_SYSTEM_INCLUDE variable if it is set when a target is created. ✨

💖 AUTOMOC 💖

Should the target be processed with auto-moc (for Qt projects). Like, should this target get the full moc treatment? 🎀

AUTOMOC is a boolean specifying whether CMake will handle the Qt moc preprocessor automatically, i.e. without having to use commands like qt4_wrap_cpp() (from the FindQt4 module), qt5_wrap_cpp() (the Qt docs page is at https://doc.qt.io/archives/qt-5.15/qtcore-cmake-qt5-wrap-cpp.html), etc. Currently, Qt versions 4 to 6 are supported. 🔥

This property is initialized by the value of the CMAKE_AUTOMOC variable if it is set when a target is created.

When this property is set ON, CMake will scan the header and source files at build time and invoke moc accordingly. 🧚

Header file processing 🌸

At configuration time, a list of header files that should be scanned by AUTOMOC is computed from the target's sources. Bestie, this is the pre-game lineup. ✨

All header files in the target's sources are added to the scan list.
For all C++ source files <source_base>.<source_extension> in the target's sources, CMake searches for
- a regular header with the same base name (<source_base>.<header_extension>) and
- a private header with the same base name and a _p suffix (<source_base>_p.<header_extension>) and adds these to the scan list.
The AUTOMOC_INCLUDE_DIRECTORIES target property may be set to explicitly tell moc what include directories to search. If not set, the default is to use the include directories from the target and its transitive closure of dependencies. 🫶

At build time, CMake scans each unknown or modified header file from the list and searches for

a Qt macro from AUTOMOC_MACRO_NAMES,
additional file dependencies from the FILE argument of a Q_PLUGIN_METADATA macro and
additional file dependencies detected by filters defined in AUTOMOC_DEPEND_FILTERS.

If a Qt macro is found, then the header will be compiled by the moc to the output file moc_<base_name>.cpp. The complete output file path is described in the section Output file location. 🌈

The header will be moc compiled again if a file from the additional file dependencies changes. 👑

Header moc output files moc_<base_name>.cpp can be included in source files. In the section Including header moc files in sources there is more information on that topic.

Source file processing 💜

At build time, CMake scans each unknown or modified C++ source file from the target's sources for

a Qt macro from AUTOMOC_MACRO_NAMES,
includes of header moc files (see Including header moc files in sources),
additional file dependencies from the FILE argument of a Q_PLUGIN_METADATA macro and
additional file dependencies detected by filters defined in AUTOMOC_DEPEND_FILTERS.

If a Qt macro is found, then the C++ source file <base>.<source_extension> is expected to as well contain an include statement

#include <<base>.moc> // or
#include "<base>.moc"

The source file then will be compiled by the moc to the output file <base>.moc. A description of the complete output file path is in section Output file location. ⭐

The source will be moc compiled again if a file from the additional file dependencies changes. 💫

Including header moc files in sources 🎀

A source file can include the moc output file of a header <header_base>.<header_extension> by using an include statement of the form

#include <moc_<header_base>.cpp> // or
#include "moc_<header_base>.cpp"

If the moc 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 Output file location. 🗺️

Output file location 📁

Included moc output files

moc output files that are included by a source file will be generated in

<AUTOGEN_BUILD_DIR>/include for single configuration generators or in
<AUTOGEN_BUILD_DIR>/include_<CONFIG> for multi configuration generators (GENERATOR_IS_MULTI_CONFIG).

Where <AUTOGEN_BUILD_DIR> is the value of the target property AUTOGEN_BUILD_DIR. 🫶

The include directory is automatically added to the target's INCLUDE_DIRECTORIES. ✨

Not included moc output files

moc output files that are not included in a source file will be generated in

<AUTOGEN_BUILD_DIR>/<SOURCE_DIR_CHECKSUM> for single configuration generators or in,
<AUTOGEN_BUILD_DIR>/include_<CONFIG>/<SOURCE_DIR_CHECKSUM> for multi configuration generators (GENERATOR_IS_MULTI_CONFIG).

Where <SOURCE_DIR_CHECKSUM> is a checksum computed from the relative parent directory path of the moc input file. This scheme allows to have moc input files with the same name in different directories. No cap, that's kinda iconic. 👑

All not included moc output files will be included automatically by the CMake generated file

<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp, or
<AUTOGEN_BUILD_DIR>/mocs_compilation_$<CONFIG>.cpp,

which is added to the target's sources. 🧚

Qt version detection 🔍

AUTOMOC enabled targets need to know the Qt major and minor version they're working with. The major version usually is provided by the INTERFACE_QT_MAJOR_VERSION property of the Qt[456]Core library, that the target links to. To find the minor version, CMake builds a list of available Qt versions from

Qt6Core_VERSION_MAJOR and Qt6Core_VERSION_MINOR variables (usually set by find_package(Qt6...))
Qt6Core_VERSION_MAJOR and Qt6Core_VERSION_MINOR directory properties
Qt5Core_VERSION_MAJOR and Qt5Core_VERSION_MINOR variables (usually set by find_package(Qt5...))
Qt5Core_VERSION_MAJOR and Qt5Core_VERSION_MINOR directory properties
QT_VERSION_MAJOR and QT_VERSION_MINOR variables (usually set by find_package(Qt4...))
QT_VERSION_MAJOR and QT_VERSION_MINOR directory properties

in the context of the add_executable() or add_library() call. 💅

Assumed INTERFACE_QT_MAJOR_VERSION 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 INTERFACE_QT_MAJOR_VERSION is not a valid number, the first entry in the list is taken. 😭

A find_package(Qt[456]...) call sets the QT/Qt[56]Core_VERSION_MAJOR/MINOR variables. If the call is in a different context than the add_executable() or add_library() call, e.g. in a function, then the version variables might not be available to the AUTOMOC enabled target. In that case the version variables can be forwarded from the find_package(Qt[456]...) calling context to the add_executable() or add_library() calling context as directory properties. The following Qt5 example demonstrates the procedure. 🦋

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)

Modifiers 💅

AUTOMOC_EXECUTABLE — The moc executable will be detected automatically, but can be forced to a certain binary using this target property.
AUTOMOC_MOC_OPTIONS — Additional command line options for moc can be set in this target property.
AUTOMOC_MACRO_NAMES — This list of Qt macro names can be extended to search for additional macros in headers and sources.
AUTOMOC_DEPEND_FILTERS — moc dependency file names can be extracted from headers or sources by defining file name filters in this target property.
AUTOMOC_COMPILER_PREDEFINES — Compiler pre definitions for moc are written to the moc_predefs.h file. The generation of this file can be enabled or disabled in this target property.
AUTOMOC_INCLUDE_DIRECTORIES — Specifies one or more include directories for AUTOMOC to pass explicitly to moc instead of automatically discovering a target's include directories.
SKIP_AUTOMOC — Sources and headers can be excluded from AUTOMOC processing by setting this source file property.
SKIP_AUTOGEN — Source files can be excluded from AUTOMOC, AUTOUIC and AUTORCC processing by setting this source file property.
AUTOGEN_SOURCE_GROUP — This global property can be used to group files generated by AUTOMOC or AUTORCC together in an IDE, e.g. in MSVS.
AUTOGEN_TARGETS_FOLDER — This global property can be used to group AUTOMOC, AUTOUIC and AUTORCC targets together in an IDE, e.g. in MSVS.

Okay bestie, finishing up the autogen globals and then we're diving headfirst into the moc properties — buckle up, this is the Qt-flavored part of the page 💅

CMAKE_GLOBAL_AUTOGEN_TARGET — when this variable is ON, a global autogen target gets generated ✨. And what does that target do? It depends on all the AUTOMOC or AUTOUIC generated <ORIGIN>_autogen targets in the project. That's the whole job. Very demure, very mindful.
AUTOGEN_PARALLEL — a target property that controls the number of moc or uic processes to start in parallel during builds. Basically the "how many little guys do we spawn at once" knob 🧚
AUTOGEN_COMMAND_LINE_LENGTH_MAX — a target property that controls the limit for when to use response files for moc or uic processes on Windows. (Windows command lines get cranky, we work around it 😭)

See the cmake-qt(7) manual for more information on using CMake with Qt 🫶

✨ AUTOMOC_COMPILER_PREDEFINES ✨

Added in version 3.10.

A boolean value that AUTOMOC uses to decide whether the compiler pre definitions file moc_predefs.h should be generated. It's giving "do we or do we not ship the predefs" 🌸

CMake generates a moc_predefs.h file containing compiler pre definitions taken from the output of the command defined in CMAKE_CXX_COMPILER_PREDEFINES_COMMAND (that's CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND in the docs, iykyk) when:

AUTOMOC is enabled,
AUTOMOC_COMPILER_PREDEFINES is enabled,
CMAKE_CXX_COMPILER_PREDEFINES_COMMAND isn't empty and
the Qt version is greater or equal 5.8.

That moc_predefs.h file — generated in AUTOGEN_BUILD_DIR, no cap — gets passed to moc as the argument to the --include option. Slay.

By default AUTOMOC_COMPILER_PREDEFINES is initialized from CMAKE_AUTOMOC_COMPILER_PREDEFINES, which is ON by default 👑

See the cmake-qt(7) manual for more information on using CMake with Qt.

🦋 AUTOMOC_DEPEND_FILTERS 🦋

Added in version 3.9.

These are filter definitions that AUTOMOC uses to extract file names from a source file — file names that then get registered as additional dependencies for the moc file of that source file. It's like telling CMake "hey, this header lowkey references this other file, trust me" 🔥

Filters are defined as KEYWORD;REGULAR_EXPRESSION pairs. First the file content is searched for KEYWORD. If it's found at least once, then file names get extracted by successively searching for REGULAR_EXPRESSION and taking the first match group.

The file name found in the first match group is searched for:

first in the vicinity of the source file
and afterwards in the target's INCLUDE_DIRECTORIES.

If any of the extracted files changes, then the moc file for the source file gets rebuilt — even when the source file itself doesn't change. Iconic behavior, honestly 🎀

If any of the extracted files is GENERATED or if it is not in the target's sources, then it might be necessary to add it to the <ORIGIN>_autogen target dependencies. See AUTOGEN_TARGET_DEPENDS for reference 👀

By default AUTOMOC_DEPEND_FILTERS is initialized from CMAKE_AUTOMOC_DEPEND_FILTERS, which is empty by default.

From Qt 5.15.0 on this variable is ignored as moc is able to output the correct dependencies. Periodt. 💀

See the cmake-qt(7) manual for more information on using CMake with Qt.

Example 1

So we've got a header file my_class.hpp that uses a custom macro JSON_FILE_MACRO, which is defined in an other header macros.hpp. We want the moc file of my_class.hpp to depend on the file name argument of JSON_FILE_MACRO. Cute, right? Let's go:

// my_class.hpp
class My_Class : public QObject
{
  Q_OBJECT
  JSON_FILE_MACRO ( "info.json" )
...
};

In CMakeLists.txt we add a filter to CMAKE_AUTOMOC_DEPEND_FILTERS like this:

list(APPEND CMAKE_AUTOMOC_DEPEND_FILTERS
  "JSON_FILE_MACRO"
  "[\n][ \t]*JSON_FILE_MACRO[ \t]*\\([ \t]*\"([^\"]+)\""
)

We assume info.json is a plain (not GENERATED) file that is listed in the target's source. Therefore we do not need to add it to AUTOGEN_TARGET_DEPENDS 🫶 easy.

Example 2

In the target my_target, a header file complex_class.hpp uses a custom macro JSON_BASED_CLASS which is defined in an other header macros.hpp:

// macros.hpp
...
#define JSON_BASED_CLASS(name, json) \
class name : public QObject \
{ \
  Q_OBJECT \
  Q_PLUGIN_METADATA(IID "demo" FILE json) \
  name() {} \
};
...

// complex_class.hpp
#pragma once
JSON_BASED_CLASS(Complex_Class, "meta.json")
// end of file

Since complex_class.hpp doesn't contain a Q_OBJECT macro it would be ignored by AUTOMOC 😭 rude. We change this by adding JSON_BASED_CLASS to CMAKE_AUTOMOC_MACRO_NAMES:

list(APPEND CMAKE_AUTOMOC_MACRO_NAMES "JSON_BASED_CLASS")

We want the moc file of complex_class.hpp to depend on meta.json. So we add a filter to CMAKE_AUTOMOC_DEPEND_FILTERS:

list(APPEND CMAKE_AUTOMOC_DEPEND_FILTERS
  "JSON_BASED_CLASS"
  "[\n^][ \t]*JSON_BASED_CLASS[ \t]*\\([^,]*,[ \t]*\"([^\"]+)\""
)

Additionally we assume meta.json is GENERATED, which is why we have to add it to AUTOGEN_TARGET_DEPENDS:

set_property(TARGET my_target APPEND PROPERTY AUTOGEN_TARGET_DEPENDS "meta.json")

🌈 AUTOMOC_EXECUTABLE 🌈

Added in version 3.14.

AUTOMOC_EXECUTABLE is a file path pointing to the moc executable to use for AUTOMOC enabled files. Set this and CMake skips the automatic detection of the moc binary, and the sanity-tests it normally runs to make sure that binary is available and working as expected. No vibe check, you just told it who to trust 💅

Usually this property does not need to be set. Only consider this property if auto-detection of moc can not work — e.g. because you are building the moc binary as part of your project. Main character build setup, honestly.

See the cmake-qt(7) manual for more information on using CMake with Qt.

🎀 AUTOMOC_INCLUDE_DIRECTORIES 🎀

Added in version 4.1.

Specifies zero or more include directories for AUTOMOC to pass explicitly to the Qt Meta-Object Compiler (moc) — instead of automatically discovering a target's include directories. Very "I'll tell you exactly where to look, bestie" energy ✨

When this property is set on a target, only the directories listed here will be used by AUTOMOC, and any other include paths get ignored. Cold. But effective.

This property may contain generator expressions.

Real talk: all directory paths in the final evaluated result must be absolute. If any non-absolute paths are present after generator expression evaluation, configuration will fail with an error 💀 no soft launch, just error.

See also the CMAKE_AUTOMOC_INCLUDE_DIRECTORIES variable, which can be used to initialize this property on all targets 👑

Example

add_library(myQtLib ...)
set_property(TARGET myQtLib PROPERTY AUTOMOC_INCLUDE_DIRECTORIES
  "${CMAKE_CURRENT_SOURCE_DIR}/include/myQtLib"
)

💜 AUTOMOC_MACRO_NAMES 💜

Added in version 3.10.

A semicolon-separated list of macro names that AUTOMOC uses to determine if a C++ file needs to be processed by moc. This is the "is this file worth moc'ing" list 🌸

This property is only used if the AUTOMOC property is ON for this target. Otherwise it's just sitting there, pretty but unused 😭

When running AUTOMOC, CMake searches for the strings listed in AUTOMOC_MACRO_NAMES in C++ source and header files. If any of the strings is found:

as the first non space string on a new line or
as the first non space string after a { on a new line,

then the file will be processed by moc 💅 that's the rule, that's the whole rule.

By default AUTOMOC_MACRO_NAMES is initialized from CMAKE_AUTOMOC_MACRO_NAMES.

See also the INTERFACE_AUTOMOC_MACRO_NAMES target property.

See the cmake-qt(7) manual for more information on using CMake with Qt.

Example

In this case the Q_OBJECT macro is hidden inside another macro called CUSTOM_MACRO. To let CMake know that source files that contain CUSTOM_MACRO need to be moc processed, we call:

set_property(TARGET tgt APPEND PROPERTY AUTOMOC_MACRO_NAMES "CUSTOM_MACRO")

Sneaky little macro, we see you 👀

🍓 AUTOMOC_MOC_OPTIONS 🍓

Additional options for moc when using AUTOMOC ✨

This property is only used if the AUTOMOC property is ON for this target. In this case, it holds additional command line options which will be used when moc is executed during the build — i.e. it is equivalent to the optional OPTIONS argument of the qt4_wrap_cpp() macro. Vintage reference, but make it fashion 💅

This property is initialized by the value of the CMAKE_AUTOMOC_MOC_OPTIONS variable if it is set when a target is created, or an empty string otherwise.

See the cmake-qt(7) manual for more information on using CMake with Qt.

EXAMPLE

In this example, the moc tool is invoked with the -D_EXTRA_DEFINE option when generating the moc file for object.cpp 👑

CMakeLists.txt

add_executable(mocOptions object.cpp main.cpp)
set_property(TARGET mocOptions PROPERTY AUTOMOC ON)
target_compile_options(mocOptions PRIVATE "-D_EXTRA_DEFINE")
set_property(TARGET mocOptions PROPERTY AUTOMOC_MOC_OPTIONS "-D_EXTRA_DEFINE")
target_link_libraries(mocOptions Qt6::Core)

object.hpp

#ifndef Object_HPP
#define Object_HPP

#include <QObject>

#ifdef _EXTRA_DEFINE
class Object : public QObject
{
Q_OBJECT
public:

  Object();

};
#endif

#endif

🧚 AUTOMOC_PATH_PREFIX 🧚

Added in version 3.16.

When this property is ON, CMake will generate the -p path prefix option for moc on AUTOMOC enabled Qt targets. Little path prefix, big vibes 🌟

To generate the path prefix, CMake tests if the header compiled by moc is in any of the target include directories. If so, CMake will compute the relative path accordingly. If the header is not in the include directories, CMake will omit the -p path prefix option — and moc usually generates a relative include path in that case. Respect the fallback 🙈

AUTOMOC_PATH_PREFIX is initialized from the variable CMAKE_AUTOMOC_PATH_PREFIX, which is OFF by default.

See the cmake-qt(7) manual for more information on using CMake with Qt.

✨ Reproducible builds ✨

Okay bestie, if you're chasing reproducible builds (iconic goal, love that for you), the manual's rec is: keep those headers that get moc-compiled hanging out in one of the target include directories (target_include_directories) and set AUTOMOC_PATH_PREFIX to ON. That combo guarantees:

moc output files are identical across different build setups — no cap,
moc output files will compile correctly even when the source and/or build directory is a symbolic link.

🌸 AUTORCC 🌸

Should the target be processed with auto-rcc (for Qt projects)? That's the whole question.

AUTORCC is a boolean, and it says whether CMake will handle the Qt rcc code generator automatically — meaning you don't have to go call things like qt4_add_resources() or qt5_add_resources() yourself, etc. Currently, Qt versions 4 to 6 are supported.

When this property is ON, CMake will handle .qrc files added as target sources at build time and invoke rcc accordingly. This property is initialized by the value of the CMAKE_AUTORCC variable if it's set when a target is created.

By default, AUTORCC is processed by a add_custom_command. If the .qrc file is GENERATED, a add_custom_target is used instead. 🎀

Heads up: when there are multiple .qrc files with the same name, CMake will generate unspecified unique output file names for rcc. So if Q_INIT_RESOURCE() or Q_CLEANUP_RESOURCE() need to be used, the .qrc file name must be unique. Don't say I didn't warn you 💀

Modifiers

AUTORCC_EXECUTABLE — the rcc executable gets detected automatically, but you can force it to a certain binary by setting this target property.
AUTORCC_OPTIONS — extra command line options for rcc, set via this target property. The corresponding AUTORCC_OPTIONS source file property can be used to specify options applied only to a specific .qrc file.
SKIP_AUTORCC — .qrc files can be excluded from AUTORCC processing by setting this source file property.
SKIP_AUTOGEN — source files can be excluded from AUTOMOC, AUTOUIC and AUTORCC processing by setting this source file property.
AUTOGEN_SOURCE_GROUP — this global property groups files generated by AUTOMOC or AUTORCC together in an IDE, e.g. in MSVS.
AUTOGEN_TARGETS_FOLDER — this global property groups AUTOMOC, AUTOUIC and AUTORCC targets together in an IDE, e.g. in MSVS.
CMAKE_GLOBAL_AUTORCC_TARGET — a global autorcc target that depends on all AUTORCC targets in the project will be generated when this variable is ON.

See the cmake-qt(7) manual for more info on using CMake with Qt. 🦋

🧚 AUTORCC_EXECUTABLE 🧚

Added in version 3.14.

AUTORCC_EXECUTABLE is a file path pointing to the rcc executable to use for AUTORCC-enabled files. Setting this property makes CMake skip the automatic detection of the rcc binary and the sanity-tests that normally run to make sure the binary is available and working as expected. 🫶

Usually this property does not need to be set. Only consider it if auto-detection of rcc can't work — e.g. because you're building the rcc binary as part of your project.

See the cmake-qt(7) manual for more info on using CMake with Qt.

⭐ AUTORCC_OPTIONS ⭐

Additional options for rcc when using AUTORCC.

This property holds extra command line options used when rcc is executed during the build via AUTORCC — i.e. it's equivalent to the optional OPTIONS argument of the qt4_add_resources() macro.

This property is initialized by the value of the CMAKE_AUTORCC_OPTIONS variable if it's set when a target is created, or an empty string otherwise.

The options set on the target may be overridden by AUTORCC_OPTIONS set on the .qrc source file. 👑

See the cmake-qt(7) manual for more info on using CMake with Qt.

EXAMPLE

# ...
set_property(TARGET tgt PROPERTY AUTORCC_OPTIONS "--compress;9")
# ...

💅 AUTOUIC 💅

Should the target be processed with auto-uic (for Qt projects)? Yes queen.

AUTOUIC is a boolean specifying whether CMake will handle the Qt uic code generator automatically — i.e. without having to use commands like qt4_wrap_ui(), qt5_wrap_ui(), etc. Currently, Qt versions 4 to 6 are supported.

This property is initialized by the value of the CMAKE_AUTOUIC variable if it's set when a target is created.

When this property is ON, CMake will scan the header and source files at build time and invoke uic accordingly. 🔥

Header and source file processing

At build time, CMake scans each header and source file from the target's sources for include statements of the form:

#include "ui_<ui_base>.h"

Once such an include statement is found in a file, CMake searches for the uic input file <ui_base>.ui:

in the vicinity of the file, and
in the AUTOUIC_SEARCH_PATHS of the target.

If the <ui_base>.ui file was found, uic is called on it to generate ui_<ui_base>.h in the directory:

<AUTOGEN_BUILD_DIR>/include for single configuration generators, or in
<AUTOGEN_BUILD_DIR>/include_<CONFIG> for multi configuration (GENERATOR_IS_MULTI_CONFIG) generators.

Where <AUTOGEN_BUILD_DIR> is the value of the target property AUTOGEN_BUILD_DIR. 🌈

The include directory is automatically added to the target's INCLUDE_DIRECTORIES.

Modifiers

AUTOUIC_EXECUTABLE — the uic executable gets detected automatically, but can be forced to a certain binary using this target property.
AUTOUIC_OPTIONS — extra command line options for uic, set via this target property. The corresponding AUTOUIC_OPTIONS source file property can specify options applied only to a specific <base_name>.ui file.
SKIP_AUTOUIC — source files can be excluded from AUTOUIC processing by setting this source file property.
SKIP_AUTOGEN — source files can be excluded from AUTOMOC, AUTOUIC and AUTORCC processing by setting this source file property.
AUTOGEN_TARGETS_FOLDER — this global property groups AUTOMOC, AUTOUIC and AUTORCC targets together in an IDE, e.g. in MSVS.
CMAKE_GLOBAL_AUTOGEN_TARGET — a global autogen target, that depends on all AUTOMOC or AUTOUIC generated <ORIGIN>_autogen targets in the project, will be generated when this variable is ON.
AUTOGEN_PARALLEL — this target property controls the number of moc or uic processes to start in parallel during builds.
AUTOGEN_COMMAND_LINE_LENGTH_MAX — this target property controls the limit for when to use response files for moc or uic processes on Windows.

See the cmake-qt(7) manual for more info on using CMake with Qt. 🍓

💜 AUTOUIC_EXECUTABLE 💜

Added in version 3.14.

AUTOUIC_EXECUTABLE is a file path pointing to the uic executable to use for AUTOUIC-enabled files. Setting this property makes CMake skip the automatic detection of the uic binary and the sanity-tests that normally run to ensure the binary is available and working as expected.

Usually this property does not need to be set. Only consider it if auto-detection of uic can't work — e.g. because you're building the uic binary as part of your project.

See the cmake-qt(7) manual for more info on using CMake with Qt.

🎀 AUTOUIC_OPTIONS 🎀

Added in version 3.0.

Additional options for uic when using AUTOUIC.

This property holds extra command line options used when uic is executed during the build via AUTOUIC — i.e. it's equivalent to the optional OPTIONS argument of the qt4_wrap_ui() macro.

This property is initialized by the value of the CMAKE_AUTOUIC_OPTIONS variable if it's set when a target is created, or an empty string otherwise.

The options set on the target may be overridden by AUTOUIC_OPTIONS set on the .ui source file.

This property may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions. ✨

See the cmake-qt(7) manual for more info on using CMake with Qt.

EXAMPLE

# ...
set_property(TARGET tgt PROPERTY AUTOUIC_OPTIONS "--no-protection")
# ...

🦋 AUTOUIC_SEARCH_PATHS 🦋

Added in version 3.9.

Search path list used by AUTOUIC to find included .ui files.

This property is initialized by the value of the CMAKE_AUTOUIC_SEARCH_PATHS variable if it's set when a target is created. Otherwise it is empty.

See the cmake-qt(7) manual for more info on using CMake with Qt.

🐚 BINARY_DIR 🐚

Added in version 3.4.

This is a read-only property that reports the value of the CMAKE_CURRENT_BINARY_DIR variable in the directory in which the target was defined. Cute and simple, no notes. 💖

🧵 BUILD_RPATH 🧵

Added in version 3.8.

A semicolon-separated list specifying runtime path (RPATH) entries to add to binaries linked in the build tree (for platforms that support it).

By default, CMake sets the runtime path of binaries in the build tree to contain search paths it knows are needed to find the shared libraries they link. Projects may set BUILD_RPATH to specify additional search paths.

Fr fr important: the build-tree runtime path will not be used for binaries in the install tree. It will be replaced with the install-tree runtime path during the installation step. 👀

See also the INSTALL_RPATH target property. 🌸

This property gets its starting value from CMAKE_BUILD_RPATH if that variable is set when the target gets created. 🫶

It's also got generator expression support, so go wild.

And bestie, there are other knobs that mess with the build-tree runtime path, so let me list them so you're not blindsided:

The CMAKE_SKIP_RPATH variable absolutely fully disables runtime paths — in both the build tree and the install tree. Like, all of them. Gone.
The SKIP_BUILD_RPATH target property disables setting any runtime path in the build tree.
The BUILD_RPATH_USE_ORIGIN target property makes the automatically-generated runtime path use entries relative to $ORIGIN.
The BUILD_WITH_INSTALL_RPATH target property makes binaries in the build tree get built with the install-tree runtime path instead.

🦋 `BUILD_RPATH_USE_ORIGIN`

Added in version 3.14.

Okay so this one's literally answering: do we use relative paths for the build RPATH? Yes or no, bestie.

It's initialized from the value of the CMAKE_BUILD_RPATH_USE_ORIGIN variable.

On platforms that support runtime paths (RPATH) with the $ORIGIN token, setting this property to TRUE turns on relative paths in the build RPATH — for executables and shared libraries that point at shared libraries living in the same build tree.

Normally, the build RPATH of a binary is stuffed with absolute paths to the directory of every shared library it links to. But the RPATH entries for directories that live inside the build tree can be made relative instead — which lets you have relocatable builds, and also helps you get reproducible builds by keeping the build directory out of the build environment. ✨

Heads up: this property does nothing on platforms that don't support the $ORIGIN token in RPATH, and it does nothing when CMAKE_SKIP_RPATH is set. The runtime path you set through the BUILD_RPATH target property is also completely unaffected by this property. No cap.

🎀 `BUILD_WITH_INSTALL_NAME_DIR`

Added in version 3.9.

BUILD_WITH_INSTALL_NAME_DIR is a boolean that says whether the macOS install_name of a target in the build tree uses the directory given by INSTALL_NAME_DIR. And this one only applies to targets on macOS — sorry to everyone else, not your era. 🙈

It's initialized from the value of the CMAKE_BUILD_WITH_INSTALL_NAME_DIR variable if that's set when the target is created.

And here's the plot twist: if this property is not set and policy CMP0068 is not NEW, then the value of BUILD_WITH_INSTALL_RPATH gets used in its place. The way that inheritance kicks in… 💀

⭐ `BUILD_WITH_INSTALL_RPATH`

BUILD_WITH_INSTALL_RPATH is a boolean that says whether to link the target in the build tree with the INSTALL_RPATH. It takes precedence over SKIP_BUILD_RPATH and saves you from needing to relink before installation. Iconic, honestly.

It's initialized from the value of the CMAKE_BUILD_WITH_INSTALL_RPATH variable if that's set when the target is created.

Also: if policy CMP0068 is not NEW, this property also controls the use of INSTALL_NAME_DIR in the build tree on macOS. Either way, the BUILD_WITH_INSTALL_NAME_DIR target property takes precedence. 👑

🌸 `BUNDLE`

This target is a CFBundle on macOS.

If a module library target has this property set to true, it gets built as a CFBundle when you build it on the Mac. It'll get the directory structure a CFBundle needs, and it'll be all set to be used for making Browser Plugins or other application resources. Cute, functional. 🎀

💖 `BUNDLE_EXTENSION`

The file extension used to name a BUNDLE, a FRAMEWORK, or a MACOSX_BUNDLE target on macOS and iOS.

Defaults? bundle, framework, or app — depends which of those target types you're dealing with. ✨

🧚 `C_EXTENSIONS`

Added in version 3.1.

A boolean saying whether compiler-specific extensions are requested. Basically: do you want the gnu flavor or the strict flavor?

This property controls whether compiler-specific extensions get used. For some compilers, that means a flag like -std=gnu11 gets added to the compile line instead of -std=c11. It's ON by default, bestie. The basic C standard level is handled separately by the C_STANDARD target property.

Go read the cmake-compile-features(7) manual for the info on compile features and the list of supported compilers — it's all there, iykyk.

This property gets initialized from the value of the CMAKE_C_EXTENSIONS variable if that's set when the target is created, and otherwise from the value of CMAKE_C_EXTENSIONS_DEFAULT (see CMP0128).

🍓 `C_STANDARD`

Added in version 3.1.

The C standard whose features you're requesting to build this target. Like, which standard do you want, bestie?

For some compilers this results in a flag such as -std=gnu11 being added to the compile line. For compilers that have no notion of a C standard level — Microsoft Visual C++ before VS 16.7, I'm looking at you — this property does absolutely nothing. 💀

Supported values are:

90 — C89/C90
99 — C99
11 — C11
17 — Added in version 3.21. C17
23 — Added in version 3.21. C23

Now here's the part you need to know: if the value you asked for doesn't result in a compile flag being added for the compiler in use, then a previous standard flag gets added instead. So if you do:

set_property(TARGET tgt PROPERTY C_STANDARD 11)

with a compiler that doesn't support -std=gnu11 or an equivalent flag, you won't get an error or a warning — nope, it'll just quietly add the -std=gnu99 or -std=gnu90 flag if those are supported. That's the "decay" behavior, and you can control it with the C_STANDARD_REQUIRED target property. Also, the C_EXTENSIONS target property lets you control whether compiler-specific extensions are enabled, per target. 🦋

See the cmake-compile-features(7) manual for info on compile features and the list of supported compilers.

This property gets initialized from the value of the CMAKE_C_STANDARD variable if that's set when the target is created.

🌈 `C_STANDARD_REQUIRED`

Added in version 3.1.

A boolean describing whether the value of C_STANDARD is an actual requirement or just a wish. 🙏

If this property is set to ON, then the value of the C_STANDARD target property is treated as a requirement — no decay allowed, periodt. If this property is OFF or unset, the C_STANDARD target property is treated as optional, and it may "decay" to a previous standard if the one you requested isn't available. For compilers that have no notion of a C standard level — again, Microsoft Visual C++ before VS 16.7 — this property has no effect.

See the cmake-compile-features(7) manual for info on compile features and the list of supported compilers.

This property gets initialized from the value of the CMAKE_C_STANDARD_REQUIRED variable if that's set when the target is created.

💅 `COMMON_LANGUAGE_RUNTIME`

Added in version 3.12.

Set this target property and the target is configured to build with C++/CLI support. Main character build config, honestly.

The Visual Studio Generators define the clr parameter depending on the value of the COMMON_LANGUAGE_RUNTIME target property:

Not Set (default) — native C++.
"" (set but empty) — mixed unmanaged/managed C++ using .NET Framework.
netcore — Added in version 3.26. Mixed unmanaged/managed C++ using .NET Core. This required VS 2019's v142 toolset or higher.
pure — managed C++.
safe — managed C++.

This property is only evaluated by the Visual Studio Generators for VS 2010 and above.

Real talk: to be able to build managed C++ targets with VS 2017 and above, the component C++/CLI support must be installed — and it may not be done by default. So check that before you come crying to me. 😭

See also IMPORTED_COMMON_LANGUAGE_RUNTIME.

🔥 `COMPATIBLE_INTERFACE_BOOL`

Properties which must be compatible with their link interface. Okay so this is the consistency police. 👑

The COMPATIBLE_INTERFACE_BOOL property may contain a list of properties for this target which must be consistent when evaluated as a boolean with the INTERFACE variant of the property in all linked dependees. Example time: if a property FOO appears in the list, then for each dependee, the INTERFACE_FOO property content in all of its dependencies must be consistent with each other, and with the FOO property in the depender.

"Consistency" here means: if the property is set, it must have the same boolean value as all the others; and if the property is not set, it just gets ignored. Simple as that. ✨

Note: 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. Don't overlap them, bestie, it's not the vibe.

💜 `COMPATIBLE_INTERFACE_NUMBER_MAX`

Properties whose maximum value from the link interface will be used.

The COMPATIBLE_INTERFACE_NUMBER_MAX property may contain a list of properties for this target whose maximum value may be read at generate time when evaluated in the INTERFACE variant of the property in all linked dependees. So if a property FOO appears in the list, then for each dependee, the INTERFACE_FOO property content in all of its dependencies will be compared with each other and with the FOO property in the depender. When the FOO property is read at generate time, the maximum value gets returned. And if the property isn't set? It's ignored.

Note: 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.

🌸 `COMPATIBLE_INTERFACE_NUMBER_MIN`

Properties whose minimum value from the link interface will be used.

So the COMPATIBLE_INTERFACE_NUMBER_MIN property can hold a whole list of property names for this target whose minimum value might get read at generate time — specifically when it's evaluated in the INTERFACE variant of the property across all the linked dependees. 💅

Like, say a property FOO shows up in that list. Then for every dependee, the INTERFACE_FOO content across all of its dependencies gets compared against each other, and against the FOO property in the depender. And when FOO gets read at generate time? You get the minimum value back. If the property isn't set at all, it's just ignored, no drama. 🫶

Heads up bestie: for each dependee, the set of properties you list here must not intersect with the set listed in any of the other Compatible Interface Properties. Like, keep those sets separate, fr fr.

✨ COMPATIBLE_INTERFACE_STRING ✨

Properties that have to be string-compatible with their link interface.

So COMPATIBLE_INTERFACE_STRING may contain a list of properties for this target which must all be the same when evaluated as a string in the INTERFACE variant across all linked dependees. 💖

Example time: if a property FOO is in the list, then for each dependee, the INTERFACE_FOO property content in all of its dependencies must equal each other, and also equal the FOO property in the depender. If the property isn't set? Ignored. Moving on. 🌸

Same rule as before, no cap: 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.

🎀 COMPILE_DEFINITIONS 🎀

Preprocessor definitions for compiling a target's sources. Iconic.

CMake also automatically drops some definitions that the native build tool just doesn't support. Rude of the build tool, but okay.

Added in version 3.26: any leading -D on an item gets removed. Slay.

Disclaimer, and this one matters: 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 doesn't seem to be escaped correctly, do not try to work around it by adding escape sequences to the value — your work-around may break in a future CMake version with improved escape support. Instead, consider defining the macro in a (configured) header file, then report the limitation. 🙈

Known limitations, in list form because tables are so not the vibe here:

# — 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.
^ < > \ " — broken in most Make tools on Windows.

CMake doesn't outright reject these values because they do work in some cases. Use with caution, bestie. ⚠️

Contents of COMPILE_DEFINITIONS may use "generator expressions" with the syntax $<...>. Check the cmake-generator-expressions(7) manual for the available expressions, and the cmake-buildsystem(7) manual for more on defining buildsystem properties. 🦋

The corresponding COMPILE_DEFINITIONS_<CONFIG> property may be set to specify per-configuration definitions. But honestly? Generator expressions should be preferred instead of setting that alternative property. 👑

🌈 COMPILE_FEATURES 🌈

Added in version 3.1.

Compiler features enabled for this target.

The features listed in this property are a subset of the features listed in the CMAKE_C_COMPILE_FEATURES, CMAKE_CUDA_COMPILE_FEATURES, and CMAKE_CXX_COMPILE_FEATURES variables. Literally just a subset, no extras. ✨

Contents of COMPILE_FEATURES may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions, and the cmake-compile-features(7) manual for info on compile features plus a list of supported compilers. 💜

⭐ COMPILE_FLAGS ⭐

Additional flags to use when compiling this target's sources.

The COMPILE_FLAGS property sets additional compiler flags used to build sources within the target. And if you want to pass additional preprocessor definitions? Use COMPILE_DEFINITIONS for that, bestie. 🎀

Note: this property has been superseded by the COMPILE_OPTIONS property. Alternatively, you can also use the target_compile_options() command instead. It's giving "legacy", iykyk. 💅

🦋 COMPILE_OPTIONS 🦋

List of options to pass to the compiler.

This property holds a semicolon-separated list of options specified so far for its target. Use the target_compile_options() command to append more options. 🌸

Order matters and here's the tea: the options get added after the flags in the CMAKE_<LANG>_FLAGS and CMAKE_<LANG>_FLAGS_<CONFIG> variables, but before those propagated from dependencies by the INTERFACE_COMPILE_OPTIONS property. ✨

This property adds compile options for all languages in a target. Want per-language compile options? Use the COMPILE_LANGUAGE generator expression. 💖

This property is initialized by the COMPILE_OPTIONS directory property when a target is created, and it's used by the generators to set the options for the compiler.

Contents of COMPILE_OPTIONS may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions, and the cmake-buildsystem(7) manual for more on defining buildsystem properties. 🫶

🎀 Option De-duplication 🎀

The final set of options used for a target gets constructed by accumulating options from the current target and the usage requirements of its dependencies. Then that set of options is de-duplicated to avoid repetition. Obsessed with no repeats, honestly.

Added in version 3.12: while it's beneficial for individual options, the de-duplication step can break up option groups. Like, -option A -option B becomes -option A B. 😭 One may specify a group of options using shell-like quoting along with a SHELL: prefix. The SHELL: prefix gets dropped, and the rest of the option string is parsed using the separate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A" "SHELL:-option B" becomes -option A -option B. Slay. 💅

👑 COMPILE_PDB_NAME 👑

Added in version 3.1.

Output name for the MS debug symbol .pdb file generated by the compiler while building source files.

This property specifies the base name for the debug symbols file. If it's not set, the default is unspecified — mysterious, main character energy. 🦋

If the PRECOMPILE_HEADERS_REUSE_FROM target is set, this property is ignored and the reusage target's value of this property is used instead. Not me being overridden like that. 😭

Added in version 4.1: contents of COMPILE_PDB_NAME may use generator expressions.

Note: the compiler-generated program database files are specified by the /Fd compiler flag and are not the same as linker-generated program database files specified by the /pdb linker flag. Use the PDB_NAME property to specify the latter. Two different vibes, don't mix them up. ⚠️

💜 COMPILE_PDB_NAME_<CONFIG> 💜

Added in version 3.1.

Per-configuration output name for the MS debug symbol .pdb file generated by the compiler while building source files.

This is the configuration-specific version of COMPILE_PDB_NAME. 🌈

Added in version 4.1: contents of COMPILE_PDB_NAME_<CONFIG> may use generator expressions.

If the PRECOMPILE_HEADERS_REUSE_FROM target is set, this property is ignored and the reusage target's value of this property is used instead.

Note: the compiler-generated program database files are specified by the /Fd compiler flag and are not the same as linker-generated program database files specified by the /pdb linker flag. Use the PDB_NAME_<CONFIG> property to specify the latter. 💅

🍓 COMPILE_PDB_OUTPUT_DIRECTORY 🍓

Added in version 3.1.

Output directory for the MS debug symbol .pdb file generated by the compiler while building source files.

This property specifies the directory into which the MS debug symbols will be placed by the compiler. 🎀

Added in version 3.12: the property value may use generator expressions. Multi-configuration generators append a per-configuration subdirectory to the specified directory — unless a generator expression is used, bestie. ⭐

This property is initialized by the value of the CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY variable if it's set when a target is created. 💖

If the PRECOMPILE_HEADERS_REUSE_FROM target is set, this property gets ghosted 🙈 — it's ignored, and the reusage target's value of this property is what actually gets used instead.

Note, bestie: the compiler-generated program database files are specified by the /Fd compiler flag and are not the same as linker-generated program database files specified by the /pdb linker flag. Use the PDB_OUTPUT_DIRECTORY property to specify the latter, okay? 💅

💾 COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>

Added in version 3.1. ✨

Per-configuration output directory for the MS debug symbol .pdb file generated by the compiler while building source files.

This is the per-configuration version of COMPILE_PDB_OUTPUT_DIRECTORY, but heads up — multi-configuration generators (Visual Studio, Xcode, Ninja Multi-Config) do NOT append a per-configuration subdirectory to the specified directory. Like, they just don't. 💀

This property is initialized by the value of the CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> variable if it is set when a target is created.

Added in version 3.12: Contents of COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> may use generator expressions. 🎀

If the PRECOMPILE_HEADERS_REUSE_FROM target is set, this property is ignored and the reusage target's value of this property is used instead.

Note: the compiler-generated program database files are specified by the /Fd compiler flag and are not the same as linker-generated program database files specified by the /pdb linker flag. Use the PDB_OUTPUT_DIRECTORY_<CONFIG> property to specify the latter. 🫶

🚨 COMPILE_WARNING_AS_ERROR

Added in version 3.24. 🔥

Specify whether to treat warnings on compile as errors. If enabled, adds a flag to treat warnings on compile as errors. If the cmake --compile-no-warning-as-error option is given on the cmake(1) command line, this property is ignored — so the CLI gets the final say, periodt. 👑

This property is not implemented for all compilers. It is silently ignored if there is no implementation for the compiler being used. The currently implemented compiler IDs are:

GNU
Clang
AppleClang
Fujitsu
FujitsuClang
IBMClang
Intel
IntelLLVM
LCC
MSVC
NVHPC
NVIDIA (CUDA)
QCC
SunPro
Tasking
TI
VisualAge
XL
XLClang

This property is initialized by the value of the variable CMAKE_COMPILE_WARNING_AS_ERROR if it is set when a target is created.

🏷️ <CONFIG>_OUTPUT_NAME

Old per-configuration target file base name. Use OUTPUT_NAME_<CONFIG> instead — she's the upgraded version, no cap. ✨

This is a configuration-specific version of the OUTPUT_NAME target property.

🎀 <CONFIG>_POSTFIX

Postfix to append to the target file name for configuration <CONFIG>.

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 CMAKE_<CONFIG>_POSTFIX variable if it is set when a target is created. This property is ignored on macOS for Frameworks and App Bundles — macOS said "not today" 🙈.

For macOS see also the FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> target property.

🧚 CROSSCOMPILING_EMULATOR

Added in version 3.3. 🦋

Use the given emulator to run executables created when crosscompiling. This command will be added as a prefix to add_test(), add_custom_command(), and add_custom_target() commands for built target system executables.

Added 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. Bestie said "args, but make it a list." 💅

Added in version 3.29: Contents of CROSSCOMPILING_EMULATOR may use generator expressions.

This property is initialized by the value of the CMAKE_CROSSCOMPILING_EMULATOR variable if it is set when a target is created.

This property is not supported when using the old form of add_test() (i.e. without the NAME and COMMAND keywords). Sorry to the old-form girlies, it's giving legacy. 😭

🌈 CUDA_ARCHITECTURES

Added in version 3.18. 🚀

List of architectures to generate device code for.

An architecture can be suffixed by either -real or -virtual 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.

A non-empty false value (e.g. OFF) disables adding architectures. This is intended to support packagers and rare cases where full control over the passed flags is required.

This property is initialized by the value of the CMAKE_CUDA_ARCHITECTURES variable if it is set when a target is created.

The CUDA_ARCHITECTURES target property must be set to a non-empty value on targets that compile CUDA sources, or it is an error — like, an actual error, not a vibe. See policy CMP0104.

The CUDA_ARCHITECTURES may be set to one of the following special values:

all — Added in version 3.23. Compile for all supported major and minor real architectures, and the highest major virtual architecture. 👑
all-major — Added in version 3.23. Compile for all supported major real architectures, and the highest major virtual architecture.
native — Added in version 3.24. Compile for the architecture(s) of the host's GPU(s). Main character energy fr fr. 🌟

🌸 Examples

set_target_properties(tgt PROPERTIES CUDA_ARCHITECTURES "35;50;72")

Generates code for real and virtual architectures 30, 50 and 72.

set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 70-real 72-virtual)

Generates code for real architecture 70 and virtual architecture 72.

set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES OFF)

CMake will not pass any architecture flags to the compiler. Iconic "we don't do that here" behavior. 💅

📦 CUDA_CUBIN_COMPILATION

Added in version 3.27. ✨

Compile CUDA sources to .cubin files instead of .obj files within Object Libraries.

For example:

add_library(mycubin OBJECT a.cu b.cu)
set_property(TARGET mycubin PROPERTY CUDA_CUBIN_COMPILATION ON)

🧩 CUDA_EXTENSIONS

Added in version 3.8. 🎀

Boolean specifying whether compiler specific extensions are requested.

This property specifies whether compiler specific extensions should be used. For some compilers, this results in adding a flag such as -std=gnu++11 instead of -std=c++11 to the compile line. This property is ON by default. The basic CUDA/C++ standard level is controlled by the CUDA_STANDARD target property.

See the cmake-compile-features(7) manual for information on compile features and a list of supported compilers.

This property is initialized by the value of the CMAKE_CUDA_EXTENSIONS variable if set when a target is created and otherwise by the value of CMAKE_CUDA_EXTENSIONS_DEFAULT (see CMP0128). 🫶

🍓 CUDA_FATBIN_COMPILATION

Added in version 3.27. 🔥

Compile CUDA sources to .fatbin files instead of .obj files within Object Libraries.

For example:

add_library(myfbins OBJECT a.cu b.cu)
set_property(TARGET myfbins PROPERTY CUDA_FATBIN_COMPILATION ON)

🌟 CUDA_OPTIX_COMPILATION

Added in version 3.27. 💜

Compile CUDA sources to .optixir files instead of .obj files within Object Libraries.

For example:

add_library(myoptix OBJECT a.cu b.cu)
set_property(TARGET myoptix PROPERTY CUDA_OPTIX_COMPILATION ON)

⭐ CUDA_PTX_COMPILATION

Added in version 3.9. 🦋

Compile CUDA sources to .ptx files instead of .obj files within Object Libraries.

For example:

add_library(myptx OBJECT a.cu b.cu)
set_property(TARGET myptx PROPERTY CUDA_PTX_COMPILATION ON)

🔗 CUDA_RESOLVE_DEVICE_SYMBOLS

Added in version 3.9. 💫

CUDA only: Enables device linking for the specific library target where required.

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 CUDA_SEPARABLE_COMPILATION 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.

If this property or CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS is unset, static libraries are treated as if it is disabled while shared, module, and executable targets behave as if it is on.

If CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS has been defined, this property is initialized to the value the variable and overriding the default behavior.

Note that device linking is not supported for Object Libraries. 🙅‍♀️

For instance:

set_property(TARGET mystaticlib PROPERTY CUDA_RESOLVE_DEVICE_SYMBOLS ON)

🧃 CUDA_RUNTIME_LIBRARY

Added in version 3.17. 🌈

Select the CUDA runtime library for use by compilers targeting the CUDA language.

The allowed case insensitive values are:

None — Link with -cudart=none or equivalent flag(s) to use no CUDA runtime library.
Shared — Link with -cudart=shared or equivalent flag(s) to use a dynamically-linked CUDA runtime library.
Static — Link with -cudart=static or equivalent flag(s) to use a statically-linked CUDA runtime library.

Contents of CUDA_RUNTIME_LIBRARY may use generator expressions.

If that property is not set then CMake uses an appropriate default value based on the compiler to select the CUDA runtime library.

Note: This property has effect only when the CUDA language is enabled. To control the CUDA runtime linking when only using the CUDA SDK with the C or C++ language we recommend using the FindCUDAToolkit module. 💖

💅 `CUDA_SEPARABLE_COMPILATION`

Added in version 3.8.

CUDA only, bestie — this one turns on separate compilation of device code.

If you set it, separable compilation gets enabled for every CUDA file in that target. That's the whole vibe.

Like, for instance:

set_property(TARGET myexe PROPERTY CUDA_SEPARABLE_COMPILATION ON)

This property is initialized by the value of the CMAKE_CUDA_SEPARABLE_COMPILATION variable if it's set when the target is created. ✨

`CUDA_STANDARD`

Added in version 3.8.

The CUDA/C++ standard whose features are requested to build this target. 🎀

So this property names the CUDA/C++ standard whose features you want for building the target. For some compilers that means a flag like -std=gnu++11 gets tacked onto the compile line.

Supported values are:

98 — CUDA C++98. Note that internally this maps to the same thing as 03.
03 — CUDA C++03
11 — CUDA C++11
14 — CUDA C++14. CMake 3.8 and later recognize 14 as a valid value, but CMake 3.9 was the first version to include support for any compiler.
17 — CUDA C++17. CMake 3.8 and later recognize 17 as a valid value, but CMake 3.18 was the first version to include support for any compiler.
20 — Added in version 3.12. CUDA C++20. CMake 3.12 and later recognize 20 as a valid value, but CMake 3.18 was the first version to include support for any compiler.
23 — Added in version 3.20. CUDA C++23
26 — Added in version 3.25. CUDA C++26. CMake 3.25 and later recognize 26 as a valid value, but no version has support for any compiler.

Okay so here's the tea: if the value you requested doesn't actually result in a compile flag being added for the compiler in use, a previous standard flag gets added instead. So this:

set_property(TARGET tgt PROPERTY CUDA_STANDARD 11)

...with a compiler that doesn't support -std=gnu++11 or an equivalent flag will not throw an error or a warning — it'll quietly add the -std=gnu++03 flag instead, if that one's supported. 🫠 That's the "decay" behavior, and you can control it with the CUDA_STANDARD_REQUIRED target property. Also, the CUDA_EXTENSIONS target property exists so you can control whether compiler-specific extensions are enabled on a per-target basis.

See the cmake-compile-features(7) manual for info on compile features and a list of supported compilers. 📚

This property is initialized by the value of the CMAKE_CUDA_STANDARD variable if it's set when the target is created.

`CUDA_STANDARD_REQUIRED`

Added in version 3.8.

A boolean that describes whether the value of CUDA_STANDARD is a requirement or just a wish. 🙏

If this property is set to ON, then the value of the CUDA_STANDARD target property is treated as a requirement. If it's OFF or unset, CUDA_STANDARD is treated as optional and may "decay" to a previous standard if the one you asked for isn't available. For compilers that have no notion of a standard level — like MSVC 1800 (Visual Studio 2013) and lower — this has no effect at all. 💀

See the cmake-compile-features(7) manual for info on compile features and a list of supported compilers.

This property is initialized by the value of the CMAKE_CUDA_STANDARD_REQUIRED variable if it's set when the target is created.

`CXX_EXTENSIONS`

Added in version 3.1.

A boolean specifying whether compiler-specific extensions are requested. ✨

It says whether compiler-specific extensions should be used. For some compilers that means a flag like -std=gnu++11 gets added to the compile line instead of -std=c++11. This property is ON by default, bestie. The basic C++ standard level is controlled by the CXX_STANDARD target property.

See the cmake-compile-features(7) manual for info on compile features and a list of supported compilers.

This property is initialized by the value of the CMAKE_CXX_EXTENSIONS variable if it's set when a target is created, and otherwise by the value of CMAKE_CXX_EXTENSIONS_DEFAULT (see CMP0128).

`CXX_MODULE_DIRS`

Added in version 3.28.

A semicolon-separated list of base directories of the target's default C++ module set — like, the file set with name and type CXX_MODULES. The property supports generator expressions. 🦋

Normally this is only set by target_sources(FILE_SET) rather than you messing with it directly, ngl.

See CXX_MODULE_DIRS_<NAME> for the list of base directories in other C++ module sets.

`CXX_MODULE_DIRS_<NAME>`

Added in version 3.28.

A semicolon-separated list of base directories of the target's <NAME> C++ module set, which has the set type CXX_MODULES. The property supports generator expressions. 🌸

Normally this is only set by target_sources(FILE_SET) rather than being manipulated directly.

See CXX_MODULE_DIRS for the list of base directories in the default C++ module set. See CXX_MODULE_SETS for the file set names of all C++ module sets.

`CXX_MODULE_SET`

Added in version 3.28.

A semicolon-separated list of files in the target's default C++ module set (i.e. the file set with name and type CXX_MODULES). If any of the paths are relative, they're computed relative to the target's source directory. The property supports generator expressions. 💖

Normally this is only set by target_sources(FILE_SET) rather than being manipulated directly.

See CXX_MODULE_SET_<NAME> for the list of files in other C++ module sets.

`CXX_MODULE_SET_<NAME>`

Added in version 3.28.

A semicolon-separated list of files in the target's <NAME> C++ module set, which has the set type CXX_MODULES. If any of the paths are relative, they're computed relative to the target's source directory. The property supports generator expressions. 🎀

Normally this is only set by target_sources(FILE_SET) rather than being manipulated directly.

See CXX_MODULE_SET for the list of files in the default C++ module set. See CXX_MODULE_SETS for the file set names of all C++ module sets.

`CXX_MODULE_SETS`

Added in version 3.28.

A read-only list of the target's PRIVATE and PUBLIC C++ module sets — i.e. all file sets with the type CXX_MODULES. Files listed in these file sets are treated as source files for the purpose of IDE integration. 👑

C++ module sets may be defined using the target_sources() command's FILE_SET option with type CXX_MODULES.

See also CXX_MODULE_SET_<NAME>, CXX_MODULE_SET and INTERFACE_CXX_MODULE_SETS.

`CXX_MODULE_STD`

Added in version 3.30.

CXX_MODULE_STD is a boolean specifying whether the target may use import std; in its C++ sources or not. 🌈

Note: this setting is only meaningful when experimental support for import std; has been enabled by the CMAKE_EXPERIMENTAL_CXX_IMPORT_STD gate. 🚪

When this property is explicitly set to ON, CMake will add a dependency to a target which provides the C++ standard library's modules for the C++ standard applied to the target. This target is only applicable within the current build and will not appear in the exported interfaces of the targets. When consumed, these targets will be reapplied as necessary.

Note: similar to the introduction of CXX_SCAN_FOR_MODULES, this property defaults to not adding import std support to targets using cxx_std_23 without an explicit request — this is to preserve existing behavior for projects using C++23 without import std. A future policy to change the default behavior is expected once the feature sees wider usage. 🔮

This property's value is not relevant for targets which disable scanning (see CXX_SCAN_FOR_MODULES). Additionally, this property only applies to targets utilizing C++23 (cxx_std_23) or newer.

The property supports generator expressions, however expressions that depend upon the configuration, the consuming target, or the linker language are not allowed. Whether a target uses import std should not depend upon things like that, because it's a static property of the target's source code. Periodt. 💅

Targets which are exported with C++ module sources will have this property's resolved value exported.

`CXX_SCAN_FOR_MODULES`

Added in version 3.28.

CXX_SCAN_FOR_MODULES is a boolean specifying whether CMake will scan C++ sources in the target for module dependencies. 🔍 See also the CXX_SCAN_FOR_MODULES per-source settings and the CXX_SCAN_FOR_MODULES file set settings. If either of those is set, it overrides the target-wide setting.

This property is initialized by the value of the CMAKE_CXX_SCAN_FOR_MODULES variable if it's set when a target is created.

When this property is set ON or unset, CMake will scan the target's CXX sources at build time and add module dependency information to the compile line as necessary. When it's set OFF, CMake will not scan the target's CXX sources at build time. 🙈

Note that scanning is only performed if C++20 or higher is enabled for the target. Scanning for modules in the target's sources belonging to file sets of type CXX_MODULES is always performed.

`CXX_STANDARD`

Added in version 3.1.

The C++ standard whose features are requested to build this target. 🔥

This property specifies the C++ standard whose features are requested to build this target. For some compilers that results in adding a flag like -std=gnu++11 to the compile line. For compilers that have no notion of a standard level — like Microsoft Visual C++ before 2015 Update 3 — this has no effect. 😭

Supported values are:

98 — C++98
11 — C++11
14 — C++14
17 — Added in version 3.8. C++17
20 — Added in version 3.12. C++20
23 — Added in version 3.20, and it's giving C++23 💅
26 — Added in version 3.25, C++26 era bestie ✨

Okay so here's the tea on that whole "decay" situation: if the value you asked for doesn't actually result in a compile flag being added for the compiler you're using, CMake just quietly adds a previous standard flag instead. No cap. So like, if you do this:

set_property(TARGET tgt PROPERTY CXX_STANDARD 11)

...with a compiler that does not support -std=gnu++11 or an equivalent flag, you will not get an error or a warning 😭 — instead it adds the -std=gnu++98 flag if that one's supported. Fr fr, it downgrades on you. You can control this "decay" behavior with the CXX_STANDARD_REQUIRED target property. Also, the CXX_EXTENSIONS target property is there to control whether compiler-specific extensions are enabled on a per-target basis. Slay.

See the cmake-compile-features(7) manual for info on compile features and a list of supported compilers 👑

This property is initialized by the value of the CMAKE_CXX_STANDARD variable if it is set when a target is created.

💖 `CXX_STANDARD_REQUIRED` 💖

Added in version 3.1.

A Boolean describing whether the value of CXX_STANDARD is a requirement — like, is this a vibe or is this the law.

If this property is set to ON, then the value of the CXX_STANDARD target property is treated as a requirement. Periodt. If this property is OFF or unset, the CXX_STANDARD target property is treated as optional and may "decay" to a previous standard if the requested one is not available. For compilers that have no notion of a standard level at all — such as MSVC 1800 (Visual Studio 2013) and lower — this has no effect. They simply don't have the range, bestie 🙈

See the cmake-compile-features(7) manual for information on compile features and a list of supported compilers.

This property is initialized by the value of the CMAKE_CXX_STANDARD_REQUIRED variable if it is set when a target is created.

Alternatively, see Requiring Language Standards.

🎀 `DEBUG_POSTFIX` 🎀

See target property <CONFIG>_POSTFIX.

This property is a special case of the more-general <CONFIG>_POSTFIX property, specifically for the DEBUG configuration. iykyk 🌸

🦋 `DEBUGGER_WORKING_DIRECTORY` 🦋

Added in version 4.0.

Sets the local debugger working directory for targets — specifically, the process launched by the debugger. Like, where the debugger's little process baby gets to hang out 💅

The property value may use generator expressions. This property is initialized by the value of the variable CMAKE_DEBUGGER_WORKING_DIRECTORY if it is set when a target is created.

Heads up though 👀 — if the VS_DEBUGGER_WORKING_DIRECTORY property is also set, it will take precedence over DEBUGGER_WORKING_DIRECTORY when using one of the Visual Studio Generators. And similarly, if XCODE_SCHEME_WORKING_DIRECTORY is set, it will override DEBUGGER_WORKING_DIRECTORY when using the Xcode generator. So those two are the main characters here and DEBUGGER_WORKING_DIRECTORY is just filling in when they're not around 😭

🌈 `DEFINE_SYMBOL` 🌈

Define a preprocessor symbol when compiling this target's sources.

CMake adds this definition when compiling sources of a SHARED library, a MODULE library, or an EXECUTABLE with ENABLE_EXPORTS enabled. If DEFINE_SYMBOL is not set, the default definition is of the form <target>_EXPORTS (with some substitutions if the target is not a valid C identifier). So it's got a little default glow-up built in ✨

The symbol is only defined while compiling the target itself and is not propagated to dependent targets. Not the sharing type, honestly.

On POSIX platforms, this can optionally be used to control the visibility of symbols.

CMake provides support for such decorations with the GenerateExportHeader module — go check that out, it ate 💅

See also the COMPILE_DEFINITIONS under Target Compile Properties.

🍓 `DEPLOYMENT_ADDITIONAL_FILES` 🍓

Added in version 3.13.

Set the WinCE project AdditionalFiles in DeploymentTool in .vcproj files generated by the Visual Studio Generators. This is useful when you want to debug on a remote WinCE device — yeah, that's a whole thing 💀 Specify additional files that will be copied to the device. For example:

set_property(TARGET ${TARGET} PROPERTY
  DEPLOYMENT_ADDITIONAL_FILES "english.lng|local_folder|remote_folder|0"
  "german.lng|local_folder|remote_folder|0")

produces:

<DeploymentTool AdditionalFiles="english.lng|local_folder|remote_folder|0;german.lng|local_folder|remote_folder|0" ... />

🧚 `DEPLOYMENT_REMOTE_DIRECTORY` 🧚

Added in version 3.6.

Set the WinCE project RemoteDirectory in DeploymentTool and RemoteExecutable in DebuggerTool in .vcproj files generated by the Visual Studio Generators. Again — super useful when you want to debug on a remote WinCE device. For example:

set_property(TARGET ${TARGET} PROPERTY
  DEPLOYMENT_REMOTE_DIRECTORY "\\FlashStorage")

produces:

<DeploymentTool RemoteDirectory="\FlashStorage" ... />
<DebuggerTool RemoteExecutable="\FlashStorage\target_file" ... />

💜 `DEPRECATION` 💜

Added in version 3.17.

Deprecation message from the imported target's developer. Like a little note from the person who made it, saying "yeah this one's past its prime bestie."

DEPRECATION is the message regarding a deprecation status to be displayed to downstream users of a target.

The message is formatted as follows:

Lines that do not start in whitespace are wrapped as paragraph text.
Lines that start in whitespace are preserved as preformatted text.

So, you know, indentation actually means something here. Iconic formatting behavior, honestly 🎀

⭐ `DISABLE_PRECOMPILE_HEADERS` ⭐

Added in version 3.16.

Disables the precompilation of header files specified by the PRECOMPILE_HEADERS property. Turning it off, basically 🙅‍♀️

If the property is not set, CMake will use the value provided by CMAKE_DISABLE_PRECOMPILE_HEADERS.

👑 `DLL_NAME_WITH_SOVERSION` 👑

Added in version 3.27.

This property controls whether the SOVERSION target property is added to the filename of generated DLL filenames for the Windows platform — which is the platform that gets selected when the WIN32 variable is set.

The value of the listed property is appended to the basename of the runtime component of the shared library target as -<SOVERSION>.

Please note that setting this property has no effect if versioned filenames are globally disabled with the CMAKE_PLATFORM_NO_VERSIONED_SONAME variable. So don't come crying to me if you set it and nothing happens 😭

🔥 `DOTNET_SDK` 🔥

Added in version 3.23.

Specify the .NET SDK for C# projects. For example: Microsoft.NET.Sdk.

This property tells the 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 COMMON_LANGUAGE_RUNTIME) — so no sneaking it in through the back door, it's simply not for you 💀

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. So like, it's not gonna check your work. You're on your own, bestie 🫶

This property may be initialized for all targets using the CMAKE_DOTNET_SDK variable.

Note: The Visual Studio Generators in this version of CMake have not yet learned to support add_custom_command() in .NET SDK-style projects. It is currently an error to attach a custom command to a target with the DOTNET_SDK property set. So don't do it. It will be a whole situation 🙈

🌸 `DOTNET_TARGET_FRAMEWORK` 🌸

Added in version 3.17.

Specify the .NET target framework.

Used to specify the .NET target framework for C++/CLI and C#. For example: netcoreapp2.1.

This property is only evaluated for Visual Studio Generators VS 2010 and above.

Can be initialized for all targets using the variable CMAKE_DOTNET_TARGET_FRAMEWORK. Easy ✨

💀 `DOTNET_TARGET_FRAMEWORK_VERSION` 💀

Added in version 3.12.

Specify the .NET target framework version.

Used to specify the .NET target framework version for C++/CLI and C#. For example: v4.5.

This property is only evaluated for Visual Studio Generators VS 2010 and above.

To initialize this variable for all targets set CMAKE_DOTNET_TARGET_FRAMEWORK or CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION. If both are set, the latter is ignored. So it's not a fight — one of them just quietly steps aside 💅

🎀 `EchoString` 🎀

A message to be displayed when the target is built.

A message to display on some generators (such as Makefile Generators) when the target is built. Just a little "hi bestie" in your build output 💖

🌟 `ENABLE_EXPORTS` 🌟

Specify whether an executable or a shared library exports symbols.

Normally an executable does not export any symbols because it is the final program — it's done, it's finished, it's the end of the line. But 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 target_link_libraries() 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:

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.
On macOS, loadable modules link to the executable itself using the -bundle_loader flag.
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.
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.

This property is initialized by the value of the CMAKE_EXECUTABLE_ENABLE_EXPORTS variable, if it is set when an executable target is created. If CMAKE_EXECUTABLE_ENABLE_EXPORTS is not set, the CMAKE_ENABLE_EXPORTS variable is used to initialize the property instead, for backward compatibility reasons. See below for alternative initialization behavior for shared library targets. Stay tuned 👀

Okay so picking right back up where we left off, bestie, we were talking about linker import files, and the tea continues:

Okay so, added in version 3.27: when you wanna link with a shared library on macOS, or link with a shared framework on any Apple platform, you can use a linker import file instead of the actual shared library itself. These linker import files are also known as text-based stubs (iykyk), and they have that .tbd file extension 💅.

The generation of these linker import files, and also their consumption, is all controlled by this property. When this property is set to true on a shared library target, CMake will literally generate a .tbd file for the library. Then other targets that link to that shared library target will use this .tbd file when linking instead of linking to the shared library binary itself. iconic behavior, honestly 🎀.

Note, bestie, listen up: For backward compatibility reasons, this property will be ignored if the XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS target property or the CMAKE_XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS variable is set to false. No cap, it just gets ignored.

For shared library targets, this property is initialized by the value of the CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS variable, if it's set when the target is created. periodt ✨.

🌸 `EXCLUDE_FROM_ALL` 🌸

So 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 it's excluded, running e.g. make in the containing directory or its ancestors will not build the target by default. it's giving "not on my watch" 💀.

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 EXCLUDE_FROM_ALL directory property is set. the way that nesting works is so real.

With EXCLUDE_FROM_ALL set to false or not set at all, the target will be brought up to date as part of doing a make install or its equivalent for whichever CMake generator you're using. slay, it stays fresh 🫶.

If a target has EXCLUDE_FROM_ALL set to true, it may still be listed in an install(TARGETS) command, but lowkey the user is responsible for ensuring that the target's build artifacts aren't missing or outdated when an install is performed. so like, don't come for CMake if things are stale, okay? 🙈.

This property may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for all the available expressions ✨.

Only the "Ninja Multi-Config" generator supports a property value that varies by configuration. For all the other generators, the value of this property must be the same for all configurations. no switching it up mid-way, bestie.

💜 See Also 💜

To exclude targets from the whole directory subtree, see the EXCLUDE_FROM_ALL directory property. entire subtree vibes 🌈.
To exclude targets from the Visual Studio solution build, use EXCLUDE_FROM_DEFAULT_BUILD.

🦋 `EXCLUDE_FROM_DEFAULT_BUILD` 🦋

Okay so this one literally excludes a target from the solution build configuration.

This property is only used by Visual Studio Generators. When set to TRUE, the target will be excluded from the build when the "Build Solution" command is run. bye felicia 👋.

This property has a per-configuration version: EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>. very demure, very configurable 🎀.

Note, and this one's important: Solution build configurations do not take project dependencies into account. If a target is excluded, it will not be built, even if another target included in the configuration depends on it. This behavior differs from the CMake-generated ALL_BUILD target and the EXCLUDE_FROM_ALL property. so like, watch out, no cap 😭.

⭐ `EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>` ⭐

This is the per-configuration version of target exclusion from Build Solution. iykyk, it's the same thing but for a specific config 💅.

This is the configuration-specific version of EXCLUDE_FROM_DEFAULT_BUILD. If the generic EXCLUDE_FROM_DEFAULT_BUILD is also set on a target, then EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG> takes precedence in configurations for which it has a value. the specific one wins, always, periodt 👑.

🌈 `EXPORT_BUILD_DATABASE` 🌈

Added in version 3.31.

Enable/Disable output of a build database for a target. it's giving "log everything" energy 📝.

This property is initialized by the value of the variable CMAKE_EXPORT_BUILD_DATABASE if it's set when a target is created.

Note, bestie: This property is meaningful only when experimental support for build databases has been enabled by the CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE gate. so like, experimental, handle with care 🧚.

🎀 `EXPORT_COMPILE_COMMANDS` 🎀

Added in version 3.20.

Enable/Disable output of compile commands during generation for a target. super useful for tooling, fr fr 💖.

This property is initialized by the value of the variable CMAKE_EXPORT_COMPILE_COMMANDS if it's set when a target is created.

🫶 `EXPORT_FIND_PACKAGE_NAME` 🫶

Note: Experimental. Gated by CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES. experimental girlies know the drill 🧪.

Control the package name associated with a dependency target when exporting a find_dependency() call in install(PACKAGE_INFO), export(PACKAGE_INFO), install(EXPORT) or export(EXPORT). This can be used to assign a package name to a package that is built by CMake and exported, or a package that was provided by FetchContent. giving everything a name, main character energy ✨.

This property is initialized by CMAKE_EXPORT_FIND_PACKAGE_NAME.

💅 `EXPORT_NAME` 💅

Exported name for target files. the name that slays on the export side 💫.

This sets the name for the IMPORTED target generated by the install(EXPORT) and export() commands. If it's not set, the logical target name is used by default. so like, default is fine if you don't wanna customize 🌸.

🌸 `EXPORT_NO_SYSTEM` 🌸

Added in version 3.25.

This property affects the behavior of the install(EXPORT) and export() commands when they install or export the target respectively. When EXPORT_NO_SYSTEM is set to true, those commands generate an imported target with the SYSTEM property set to false. it's a whole vibe shift, no cap.

See the NO_SYSTEM_FROM_IMPORTED target property to set this behavior on the target consuming the include directories rather than the one providing them. so like, you can flip it from either side, iykyk 🦋.

🔥 `EXPORT_PROPERTIES` 🔥

Added in version 3.12.

List additional properties to export for a target. it's giving "give the people more" ✨.

This property contains a list of property names that should be exported by the install(EXPORT) and export() commands. By default only a limited number of properties are exported. This property can be used to additionally export other properties as well. so like, expand the export menu, bestie 🍓.

Properties starting with INTERFACE_ or IMPORTED_ are not allowed, as they are reserved for internal CMake use. hands off, those are CMake's 💀.

Properties containing generator expressions are also not allowed. sorry bestie, no expressions here 🙈.

Note: 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. so like, watch out for backwards compat, no cap 😭.

🧚 `FASTBUILD_CACHING` 🧚

Added in version 4.2.

A target property that controls whether caching is enabled for the given target in the generated fbuild.bff. giving cache-control energy, honestly 💅.

If set to OFF, the FASTBuild generator disables caching features for this target. This is useful for targets that are known to be unreliably cached or not worth caching. so like, if caching is giving you grief, just turn it off 🫶.

Example:

set_property(TARGET my_target PROPERTY FASTBUILD_CACHING OFF)

Defaults to ON. slay.

🍓 `FASTBUILD_DISTRIBUTION` 🍓

Added in version 4.2.

A target property that controls whether distribution is enabled for the given target in the generated fbuild.bff. spreading the build across machines, iconic 🌈.

If set to OFF, the FASTBuild generator disables distributed compilation for this target. This can be helpful for targets that are fast to build locally or are incompatible with distributed execution. some things are just better done locally, fr fr 💖.

Example:

set_property(TARGET my_target PROPERTY FASTBUILD_DISTRIBUTION OFF)

Defaults to ON. periodt.

🎀 `FOLDER` 🎀

For IDEs that present targets using a folder hierarchy, this property specifies the name of the folder to place the target under. To nest folders, use FOLDER values such as GUI/Dialogs with / characters separating folder levels. Targets with no FOLDER property will appear as top level entities. Targets with the same FOLDER property value will appear in the same folder as siblings. organization is self-care, bestie 💅✨.

Only some CMake generators honor the FOLDER property (e.g. Xcode or any of the Visual Studio generators). Those generators that don't will simply ignore it. so like, not everyone appreciates your folder aesthetic, and that's fine 🙈.

This property is initialized by the value of the variable CMAKE_FOLDER if it's set when a target is created.

The global property USE_FOLDERS must be set to true, otherwise the FOLDER property is ignored. so like, gatekeeping is real, gotta flip that flag first 🔑.

🌟 `Fortran_BUILDING_INTRINSIC_MODULES` 🌟

Added in version 4.0.

Instructs the CMake Fortran preprocessor that the target is building Fortran intrinsics for building a Fortran compiler. very niche, very specific, very serve 🧚.

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. so like, know which side you're on, no cap 💀.

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. it's giving "trust the compiler" energy 🫶.

🦋 `Fortran_FORMAT` 🦋

Set to FIXED or FREE to indicate the Fortran source layout. two options, choose your fighter 💫.

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 Fortran_FORMAT property to change the format of a specific source file. so like, whole-target vibes or per-file vibes, your call 🌸. If the variable CMAKE_Fortran_FORMAT is set when a target is created, its value is used to initialize this property.

🌈 `Fortran_MODULE_DIRECTORY` 🌈

Specify output directory for Fortran modules provided by the target. a home for your modules, iconic 🏠.

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's source directory. If the variable CMAKE_Fortran_MODULE_DIRECTORY is set when a target is created, its value is used to initialize this property. so like, default location is fine but you can customize, slay 💖.

okay so, continuing right where we left off on Fortran_MODULE_DIRECTORY — 💅

When you're rolling with one of the Visual Studio Generators <# visual-studio-generators> and the Intel Fortran plugin is chillin' in Visual Studio, a subdirectory named after the configuration gets appended to the path where modules are created. So like — if Fortran_MODULE_DIRECTORY is set to C:/some/path, your modules are gonna end up in C:/some/path/Debug (or C:/some/path/Release, etc., iykyk) when an Intel Fortran .vfproj file gets generated. But with any other generator? They land in plain old C:/some/path. ✨

heads up bestie: some compilers will automatically search the module output directory for modules that get USEd during compilation... and some absolutely will not. 😭 So if your sources USE modules, their location has to be specified by INCLUDE_DIRECTORIES <#prop_tgt:INCLUDE_DIRECTORIES> — regardless of this property. No cap.

<butterfly>Fortran_PREPROCESS</butterfly> 🦋

Added in version 3.18.

This one controls whether the Fortran source file should be unconditionally preprocessed. Iconic behavior switch, honestly.

If it's unset or empty → you're relying on the compiler to figure out whether the file needs preprocessing.
If it's explicitly set to OFF → the file does not need to be preprocessed.
If it's explicitly set to ON → the file does need to be preprocessed as part of the compilation step. Periodt.

When you're using the Ninja <#generator:Ninja> generator, all source files get preprocessed first, so that module dependency info can be generated. Setting this property to OFF makes Ninja skip that step. 🔥

Use the source-specific Fortran_PREPROCESS <#prop_sf:Fortran_PREPROCESS> property if it's just a single file that needs the preprocess treatment. And if the variable CMAKE_Fortran_PREPROCESS <#variable:CMAKE_Fortran_PREPROCESS> is set when a target is created, its value initializes this property.

Note: for some compilers — specifically NAG, PGI and Solaris Studio — setting this to OFF will have literally no effect. 💀

FRAMEWORK 🎀

Build a SHARED or STATIC library as a Framework Bundle on macOS and iOS. It's giving main character energy for Apple platforms.

If such a library target has this property set to TRUE, it will be built as a framework when built on the macOS and iOS. It'll have the whole directory structure required for a framework, and it'll be suitable to be used with the -framework option. 🌸 This property is initialized by the value of the CMAKE_FRAMEWORK <#variable:CMAKE_FRAMEWORK> variable if it's set when a target is created.

Wanna customize the Info.plist file in the framework? Use the MACOSX_FRAMEWORK_INFO_PLIST <#prop_tgt:MACOSX_FRAMEWORK_INFO_PLIST> target property. 🫶

For macOS, also peep the FRAMEWORK_VERSION <#prop_tgt:FRAMEWORK_VERSION> target property.

Example of creation dynamicFramework:

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"
)

FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> 💜

Added in version 3.18.

Postfix to append to the framework file name for configuration <CONFIG>, when you're using a multi-config generator (like Xcode <#generator:Xcode> and Ninja Multi-Config <#generator:Ninja Multi-Config>). Obsessed with a good postfix. ✨

When building with configuration <CONFIG>, the value of this property gets appended to the framework file name built on disk.

For example — given a framework called my_fw, a value of _debug for the FRAMEWORK_MULTI_CONFIG_POSTFIX_DEBUG property, and Debug;Release in CMAKE_CONFIGURATION_TYPES <#variable:CMAKE_CONFIGURATION_TYPES>, the following relevant files would be created for the Debug and Release configurations:

Release/my_fw.framework/my_fw
Release/my_fw.framework/Versions/A/my_fw
Debug/my_fw.framework/my_fw_debug
Debug/my_fw.framework/Versions/A/my_fw_debug

For framework targets, this property is initialized by the value of the CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> <# variable:CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>> variable if it's set when a target is created.

This property is ignored for non-framework targets, and when using single config generators. So don't come crying to me when it doesn't do anything. 🙈

FRAMEWORK_VERSION 🧚

Added in version 3.4.

Version of a framework created using the FRAMEWORK <#prop_tgt:FRAMEWORK> target property (e.g. A). Simple as that, bestie.

This property only affects macOS, because iOS doesn't have a versioned directory structure. 💅

GENERATOR_FILE_NAME ⭐

The generator's file for this target.

It's an internal property used by some generators to record the name of the project or dsp file associated with this target. Ngl, it's kinda an inside-baseball thing. Note that at configure time, this property is only set for targets created by include_external_msproject() <#command:include_external_msproject>.

GHS_INTEGRITY_APP 🍓

Added in version 3.14.

An ON / OFF boolean that determines if an executable target should be treated as an Integrity Application.

If no value is set, and a .int file is added as a source file to the executable target, it'll be treated as an Integrity Application. Automatic, slay.

Supported on Green Hills MULTI <#generator:Green Hills MULTI>. 👑

GHS_NO_SOURCE_GROUP_FILE 🌈

Added in version 3.14.

An ON / OFF boolean controlling whether the project file for a target should be one single file or multiple files. Choose your fighter.

The default behavior — or whenever the property is OFF — is to generate a project file for the target, and then a sub-project file for each source group.

When this property is ON, or if CMAKE_GHS_NO_SOURCE_GROUP_FILE <# variable:CMAKE_GHS_NO_SOURCE_GROUP_FILE> is ON, then only a single project file gets generated for the target.

Supported on Green Hills MULTI <#generator:Green Hills MULTI>. 💚

GNUtoMS 🔥

Convert GNU import library (.dll.a) to MS format (.lib). The glow-up of file formats, honestly.

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 (.dll.a) from GNU to MS format (.lib). Both import libraries will be installed by install(TARGETS) <#targets> and exported by install(EXPORT) <#export> and export() <#command:export> — so they can be linked by applications with either GNU- or MS-compatible tools. Both, not either-or. We contain multitudes. 🫶

If the variable CMAKE_GNUtoMS is set when a target is created, its value is used to initialize this property. But listen — the variable must be set prior to the first command that enables a language, such as project() <# command:project> or enable_language() <#command:enable_language>. CMake provides the variable as an option to the user automatically when configuring on Windows with GNU tools. Convenient!

HAS_CXX 💀

Link the target using the C++ linker tool (obsolete).

It's equivalent to setting the LINKER_LANGUAGE <# prop_tgt:LINKER_LANGUAGE> property to CXX. That's it. That's the whole thing. It's giving "we have a modern way at home." 🙈

HEADER_DIRS 🎀

Added in version 3.23.

A semicolon-separated list of base directories of the target's default header set (i.e. the file set with name and type HEADERS). This property supports generator expressions <#manual:cmake-generator-expressions(7)>. ✨

This property is normally only set by target_sources(FILE_SET) <# command:target_sources> rather than being manipulated directly. Like, you can poke it yourself, but that's not the vibe.

See HEADER_DIRS_<NAME> <#prop_tgt:HEADER_DIRS_<NAME>> for the list of base directories in other header sets.

HEADER_DIRS_<NAME> 🌸

Added in version 3.23.

A semicolon-separated list of base directories of the target's <NAME> header set, which has the set type HEADERS. This property supports generator expressions <#manual:cmake-generator-expressions(7)>. 💖

This property is normally only set by target_sources(FILE_SET) <# command:target_sources> rather than being manipulated directly.

See HEADER_DIRS <#prop_tgt:HEADER_DIRS> for the list of base directories in the default header set. And see HEADER_SETS <#prop_tgt:HEADER_SETS> for the file set names of all header sets. It's all connected, bestie — one big beautiful header ecosystem. 🦋

HEADER_SET ⭐

Added in version 3.23.

A semicolon-separated list of files in the target's default header set (i.e. the file set with name and type HEADERS). If any of the paths are relative, they get computed relative to the target's source directory. The property supports generator expressions <# manual:cmake-generator-expressions(7)>. 🔥

This property is normally only set by target_sources(FILE_SET) <# command:target_sources> rather than being manipulated directly.

See HEADER_SET_<NAME> <#prop_tgt:HEADER_SET_<NAME>> for the list of files in other header sets.

HEADER_SET_<NAME> 🧚

Added in version 3.23.

A semicolon-separated list of files in the target's <NAME> header set, which has the set type HEADERS. If any of the paths are relative, they're computed relative to the target's source directory. The property supports generator expressions <#manual:cmake-generator-expressions(7)>. 💜

This property is normally only set by target_sources(FILE_SET) <# command:target_sources> rather than being manipulated directly.

See HEADER_SET <#prop_tgt:HEADER_SET> for the list of files in the default header set. And see HEADER_SETS <#prop_tgt:HEADER_SETS> for the file set names of all header sets. 🎀

HEADER_SETS 👑

Added in version 3.23.

A read-only list of the target's PRIVATE and PUBLIC header sets (i.e. all file sets with the type HEADERS). Files listed in these file sets are treated as source files for the purpose of IDE integration. Those files also get their HEADER_FILE_ONLY <#prop_sf:HEADER_FILE_ONLY> property set to TRUE. Automatic. Slay. ✨

Header sets may be defined using the target_sources() <# command:target_sources> command FILE_SET option with type HEADERS.

See also HEADER_SET_<NAME> <#prop_tgt:HEADER_SET_<NAME>>, HEADER_SET <# prop_tgt:HEADER_SET> and INTERFACE_HEADER_SETS <# prop_tgt:INTERFACE_HEADER_SETS>. The whole squad. 🫶

HIP_ARCHITECTURES 🔥

Added in version 3.21.

A list of GPU architectures for which to generate device code. Architecture names are interpreted based on CMAKE_HIP_PLATFORM <# variable:CMAKE_HIP_PLATFORM>. 🦋

A non-empty false value (e.g. OFF) disables adding architectures. This is intended to support packagers and those rare cases where you need full control over the passed flags. iykyk.

This property is initialized by the value of the CMAKE_HIP_ARCHITECTURES <#variable:CMAKE_HIP_ARCHITECTURES> variable if it's set when a target is created.

Okay so 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. So therefore — the HIP_ARCHITECTURES target property should be set on targets that compile or link with any HIP sources. Both kinds, bestie. 💅

Examples 🌈

set_property(TARGET tgt PROPERTY HIP_ARCHITECTURES gfx801 gfx900)

Generates code for both gfx801 and gfx900. Double the architectures, double the slay. ⭐

HIP_EXTENSIONS 🍓

Added in version 3.21.

Okay so this flag is a boolean and it's literally just "do we want the compiler's special little extra extensions or not" ✨

It says whether compiler-specific extensions should get used. For some compilers, that means adding a flag like -std=gnu++11 instead of -std=c++11 to the compile line. This property is ON by default 💚 and the basic HIP/C++ standard level is controlled by the HIP_STANDARD target property.

Peep the cmake-compile-features(7) manual for the deets on compile features and a whole list of supported compilers 🫶

This property gets initialized by the value of the CMAKE_HIP_EXTENSIONS variable if it's set when the target is created, and otherwise by the value of CMAKE_HIP_EXTENSIONS_DEFAULT (that's CMAKE_<LANG>_EXTENSIONS_DEFAULT — see CMP0128 👀).

HIP_STANDARD

Added in version 3.21. 🎀

The HIP/C++ standard you're requesting to build this target with, bestie.

Supported values, and yes I'm listing all of them:

98 — HIP C++98
11 — HIP C++11
14 — HIP C++14
17 — HIP C++17
20 — HIP C++20
23 — HIP C++23
26 — Added in version 3.25. HIP C++26. CMake 3.25 and later recognize 26 as a valid value, but no version has support for any compiler 💀 (yes, it's a valid value that nobody can actually use yet, iconic honestly)

Okay so here's the vibe: if the value you requested doesn't result in a compile flag being added for the compiler in use, a previous standard flag gets added instead. Which means doing this:

set_property(TARGET tgt PROPERTY HIP_STANDARD 11)

with a compiler that doesn't support -std=gnu++11 or an equivalent flag will not throw an error or a warning 😭 it'll instead add the -std=gnu++98 flag if that one's supported. That "decay" behavior is controllable with the HIP_STANDARD_REQUIRED target property. Also, the HIP_EXTENSIONS target property lets you control whether compiler-specific extensions are enabled on a per-target basis 🌸

Go read the cmake-compile-features(7) manual for info on compile features and a list of supported compilers, fr fr.

This property is initialized by the value of the CMAKE_HIP_STANDARD variable if it's set when a target is created.

HIP_STANDARD_REQUIRED

Added in version 3.21. 💅

A boolean describing whether the value of HIP_STANDARD is an actual requirement or just a suggestion.

If this property is set to ON, then whatever value HIP_STANDARD holds is treated as a requirement — no take-backs. If this property is OFF or unset, HIP_STANDARD is treated as optional and it may "decay" to a previous standard if the one you asked for isn't available 🍂

See the cmake-compile-features(7) manual for info on compile features and the list of supported compilers.

This property is initialized by the value of the CMAKE_HIP_STANDARD_REQUIRED variable if it's set when a target is created.

IMPLICIT_DEPENDS_INCLUDE_TRANSFORM

Set up #include line transforms for dependencies in a target ✨

This property specifies rules for transforming macro-like #include lines while implicit dependency scanning happens on C and C++ source files. The list of rules has to be semicolon-separated, with each entry looking like A_MACRO(%)=value-with-% (and the % has to be literal, no cap). During dependency scanning, occurrences of A_MACRO(...) on #include lines get replaced by the value you gave, with the macro argument substituted in for %. For example, this entry:

MYDIR(%)=<mydir/%>

will convert lines like this:

#include MYDIR(myheader.h)

into this:

#include <mydir/myheader.h>

which lets the dependency actually be followed 🔥

This property applies to sources in the target it's set on.

IMPORTED

Read-only indicator of whether a target is IMPORTED 👑

The boolean value of this property is True for targets created with the IMPORTED option to add_executable() or add_library(). It's False for targets built within the project.

IMPORTED_COMMON_LANGUAGE_RUNTIME

Added in version 3.12. 🦋

Property that defines whether the target uses C++/CLI.

It's ignored for non-imported targets 🙈

See also the COMMON_LANGUAGE_RUNTIME target property.

IMPORTED_CONFIGURATIONS

The configurations provided for an imported target 💖

Set this to the list of configuration names that are available for an imported target. For each configuration you name, the imported target's artifacts have to be specified in other target properties:

IMPORTED_LOCATION_<CONFIG>, or
IMPORTED_IMPLIB_<CONFIG> (on DLL platforms, on AIX for Executables or on Apple for Shared Libraries), or
IMPORTED_OBJECTS_<CONFIG> (for Object Libraries), or
IMPORTED_LIBNAME_<CONFIG> (for Interface Libraries).

The configuration names correspond to the ones defined in the project the target is imported from. If the importing project uses a different set of configurations, the names may be mapped using the MAP_IMPORTED_CONFIG_<CONFIG> target property 🔀

The IMPORTED_CONFIGURATIONS property is ignored for non-imported targets.

IMPORTED_CXX_MODULES_COMPILE_DEFINITIONS

Added in version 3.28. 🧚

Preprocessor definitions for compiling an IMPORTED target's C++ module sources.

CMake will automatically drop some definitions that aren't supported by the native build tool, so don't stress 💅

IMPORTED_CXX_MODULES_COMPILE_FEATURES

Added in version 3.28. ⭐

Compiler features enabled for this IMPORTED target's C++ modules.

The value of this property is used by the generators to set the include paths for the compiler.

IMPORTED_CXX_MODULES_COMPILE_OPTIONS

Added in version 3.28. 🌈

List of options to pass to the compiler for this IMPORTED target's C++ modules.

Option De-duplication

The final set of options used for a target gets constructed by accumulating options from the current target and the usage requirements of its dependencies. Then that set gets de-duplicated so you don't get the same option screaming at you twice 🔁

Added in version 3.12: while de-duplication is great for individual options, it can totally break up option groups 😭 For example, -option A -option B becomes -option A B. So you can specify a group of options using shell-like quoting plus a SHELL: prefix. The SHELL: prefix gets dropped, and the rest of the option string is parsed using separate_arguments() in UNIX_COMMAND mode. For example, "SHELL:-option A" "SHELL:-option B" becomes -option A -option B 🎀

IMPORTED_CXX_MODULES_<CONFIG>

Added in version 3.28. 💜

A list of C++ module specifications available with the target for configuration <CONFIG>. Each item in the list is of the form <NAME>=<INTERFACE>[,<BMI>]*, where <NAME> is the name of the module, <INTERFACE> is its module interface unit, and any number of available <BMI> files are provided.

Note: CMake currently does not use the <BMI> files, because there's only limited support for determining whether an existing <BMI> file is suitable for a given importer of the module it represents. So yeah, they're there, they're just not being used yet 🙈

IMPORTED_CXX_MODULES_INCLUDE_DIRECTORIES

Added in version 3.28. 🌸

List of preprocessor include file search directories when compiling C++ modules for IMPORTED targets.

The value of this property is used by the generators to set the include paths for the compiler.

IMPORTED_CXX_MODULES_LINK_LIBRARIES

Added in version 3.28. 🔥

List of direct dependencies to use for usage requirements for C++ modules in the target's C++ modules.

IMPORTED_GLOBAL

Added in version 3.11. 👑

Indication of whether an IMPORTED target is globally visible.

The boolean value of this property is True for targets created with the IMPORTED GLOBAL options to add_executable() or add_library(). It is always False for targets built within the project.

For targets created with the IMPORTED option to add_executable() or add_library() but without the additional GLOBAL option, this is False too. However, setting this property for such a locally IMPORTED target to True promotes that target to global scope promotion arc!! ✨ And this promotion can only be done in the same directory where that IMPORTED target was created in the first place. Rules are rules.

Note: Once an imported target has been made global, it cannot be changed back to non-global. So 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 💀

Note: Local ALIAS targets created before promoting an IMPORTED target from LOCAL to GLOBAL keep their initial scope (see the ALIAS_GLOBAL target property). They don't get the glow-up, sorry bestie 😭

IMPORTED_IMPLIB

Full path to the import library for an IMPORTED target 🎯

This property may be set:

On DLL platforms, to the location of the .lib part of the DLL.
Added in version 3.16: On AIX, to an import file (e.g. .imp) created for executables that export symbols (see the ENABLE_EXPORTS target property).
Added in version 3.27: On Apple platforms, to an import file (e.g. .tbd) created for shared libraries or frameworks (see the ENABLE_EXPORTS target property). For frameworks, this is the location of the .tbd file symlink just inside the framework folder.
Added in version 3.28: On non-DLL platforms, to the location of a shared library. When set without also specifying an IMPORTED_LOCATION, the library is considered to be a stub, and its location will not be added as a runtime search path to dependents that link it. Important!! 🫶

Changed in version 3.28: if an imported target is an Apple framework or XCFramework, the preferred arrangement is to set IMPORTED_LOCATION to the .framework or .xcframework directory. CMake will then find the relevant .tbd file inside that framework or XCFramework automatically, without requiring IMPORTED_IMPLIB to be set. Slay, less work for you 💅

okay so the IMPORTED_IMPLIB target property can be overridden for a given configuration <CONFIG> by the configuration-specific IMPORTED_IMPLIB_<CONFIG> target property 💖. Also, the MAP_IMPORTED_CONFIG_<CONFIG> target property can be used to map between a project's configurations and those of an imported target. If none of these is set, then the name of any other configuration listed in the IMPORTED_CONFIGURATIONS target property may be selected and its IMPORTED_IMPLIB_<CONFIG> value used ✨.

This property is ignored for non-imported targets 🫶.

🎀 `IMPORTED_IMPLIB_<CONFIG>` 🎀

<CONFIG>-specific version of the IMPORTED_IMPLIB property.

Configuration names correspond to those provided by the project from which the target is imported 💅.

🦋 `IMPORTED_LIBNAME` 🦋

Added in version 3.8.

Specify the link library name for an imported Interface Library 🌸.

An interface library builds no library file itself but does specify usage requirements for its consumers. The IMPORTED_LIBNAME 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 ✨.

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 foo but may not be a path (e.g. /usr/lib/libfoo.so) or a flag (e.g. -Wl,...). The name is never treated as a library target name even if it happens to name one 👑.

The IMPORTED_LIBNAME property is allowed only on imported Interface Libraries and is rejected on targets of other types (for which the IMPORTED_LOCATION target property may be used) 💀.

🌈 `IMPORTED_LIBNAME_<CONFIG>` 🌈

Added in version 3.8.

<CONFIG>-specific version of the IMPORTED_LIBNAME property.

Configuration names correspond to those provided by the project from which the target is imported 🧚.

🍓 `IMPORTED_LINK_DEPENDENT_LIBRARIES` 🍓

Dependent shared libraries of an imported shared library 💖.

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 INTERFACE_LINK_LIBRARIES 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 💅.

💜 `IMPORTED_LINK_DEPENDENT_LIBRARIES_<CONFIG>` 💜

<CONFIG>-specific version of IMPORTED_LINK_DEPENDENT_LIBRARIES.

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 ✨.

🔥 `IMPORTED_LINK_INTERFACE_LANGUAGES` 🔥

Languages compiled into an IMPORTED static library.

Set this to the list of languages of source files compiled to produce a STATIC IMPORTED library (such as C or CXX). 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 👑

This property is ignored for targets that are not STATIC libraries. This property is ignored for non-imported targets 💀.

🌸 `IMPORTED_LINK_INTERFACE_LANGUAGES_<CONFIG>` 🌸

<CONFIG>-specific version of IMPORTED_LINK_INTERFACE_LANGUAGES.

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 🫶.

⭐ `IMPORTED_LINK_INTERFACE_LIBRARIES` ⭐

Transitive link interface of an IMPORTED target.

Set this to the list of libraries whose interface is included when an IMPORTED library target is linked to another target. The libraries will be included on the link line for the target. Unlike the LINK_INTERFACE_LIBRARIES property, this property applies to all imported target types, including STATIC libraries. This property is ignored for non-imported targets 💅.

This property is ignored if the target also has a non-empty INTERFACE_LINK_LIBRARIES property.

🚨 deprecated — this property is deprecated. Use INTERFACE_LINK_LIBRARIES instead 💀.

🎀 `IMPORTED_LINK_INTERFACE_LIBRARIES_<CONFIG>` 🎀

<CONFIG>-specific version of IMPORTED_LINK_INTERFACE_LIBRARIES.

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 ✨.

This property is ignored if the target also has a non-empty INTERFACE_LINK_LIBRARIES property.

🚨 deprecated — this property is deprecated. Use INTERFACE_LINK_LIBRARIES instead 💀.

🦋 `IMPORTED_LINK_INTERFACE_MULTIPLICITY` 🦋

Repetition count for cycles of IMPORTED static libraries.

This is LINK_INTERFACE_MULTIPLICITY for IMPORTED targets 💖.

🌈 `IMPORTED_LINK_INTERFACE_MULTIPLICITY_<CONFIG>` 🌈

<CONFIG>-specific version of IMPORTED_LINK_INTERFACE_MULTIPLICITY.

If set, this property completely overrides the generic property for the named configuration ✨.

👑 `IMPORTED_LOCATION` 👑

Full path to the main file on disk for an IMPORTED target.

Set this to the location of an IMPORTED target file on disk. For executables this is the location of the executable file. For STATIC libraries and modules this is the location of the library or module. For SHARED 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 Contents/MacOS 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 .dll part of the library. For UNKNOWN libraries this is the location of the file to be linked. Ignored for non-imported targets 💅.

Added in version 3.28: For ordinary frameworks on Apple platforms, this may be the location of the .framework folder itself. For XCFrameworks, it may be the location of the .xcframework folder, in which case any target that links against it will get the selected library's Headers directory as a usage requirement ✨.

The IMPORTED_LOCATION target property may be overridden for a given configuration <CONFIG> by the configuration-specific IMPORTED_LOCATION_<CONFIG> target property. Furthermore, the MAP_IMPORTED_CONFIG_<CONFIG> target property may be used to map between a project's configurations and those of an imported target. If none of these is set then the name of any other configuration listed in the IMPORTED_CONFIGURATIONS target property may be selected and its IMPORTED_LOCATION_<CONFIG> value used 🫶.

To get the location of an imported target read one of the LOCATION or LOCATION_<CONFIG> properties 👑

For platforms with import libraries (e.g. Windows, AIX or Apple) see also IMPORTED_IMPLIB 🌸.

💜 `IMPORTED_LOCATION_<CONFIG>` 💜

<CONFIG>-specific version of IMPORTED_LOCATION property.

Configuration names correspond to those provided by the project from which the target is imported 🧚.

🍓 `IMPORTED_NO_SONAME` 🍓

Specifies that an IMPORTED shared library target has no soname.

Set this property to true for an imported shared library file that has no soname 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 soname. Ignored for non-imported targets 💅.

🔥 `IMPORTED_NO_SONAME_<CONFIG>` 🔥

<CONFIG>-specific version of IMPORTED_NO_SONAME property.

Configuration names correspond to those provided by the project from which the target is imported ✨.

🌈 `IMPORTED_OBJECTS` 🌈

Added in version 3.9.

A semicolon-separated list of absolute paths to the object files on disk for an imported object library 💖.

Ignored for non-imported targets 💀.

Projects may skip IMPORTED_OBJECTS if the configuration-specific property IMPORTED_OBJECTS_<CONFIG> is set instead, except in situations as noted in the section below 🫶.

🌟 Xcode Generator Considerations 🌟

Added in version 3.20.

For Apple platforms, a project may be built for more than one architecture. This is controlled by the CMAKE_OSX_ARCHITECTURES variable. For all but the Xcode generator, CMake invokes compilers once per source file and passes multiple -arch flags, leading to a single object file which will be a universal binary. Such object files work well when listed in the IMPORTED_OBJECTS of a separate CMake build, even for the Xcode generator. But producing such object files with the Xcode 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 💅.

A further complication with the Xcode generator is that when targeting device platforms (iOS, tvOS, visionOS or watchOS), the Xcode 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 simulator SDKs (e.g. arm64 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 💖.

Okay so the tea on IMPORTED_OBJECTS is that it does not support generator expressions — like, at all — so every single file it lists has to be valid for every architecture and SDK. 😭 If you're incorporating object files that aren't universal binaries, then the path and/or the file name of each object file has to somehow encapsulate the different architectures and SDKs. Like, it's gotta be in the name, bestie. 💅

With the Xcode <#generator:Xcode> generator you can use Xcode variables of the form $(...) to represent those aspects, and Xcode will substitute the appropriate values at build time. CMake doesn't interpret these variables — it just embeds them unchanged in the Xcode project file. So $(CURRENT_ARCH) represents the architecture, while $(EFFECTIVE_PLATFORM_NAME) differentiates between SDKs. 🎀

Here's one example of how those two variables can be used to refer to an object file whose location depends on both the SDK and the architecture:

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

In some cases you may want to have configuration-specific object files as well 👀 — the $(CONFIGURATION) Xcode variable is often used for that, and you can absolutely use it in conjunction with the others mentioned above:

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

When any Xcode variable is used, CMake is not able to fully evaluate the path(s) at configure time. One consequence of this — and this is the important part, don't skip it — is that the configuration-specific IMPORTED_OBJECTS_<CONFIG> <#prop_tgt:IMPORTED_OBJECTS_<CONFIG>> properties cannot be used, since CMake cannot determine whether an object file exists at a particular <CONFIG> location. 🫠 The IMPORTED_OBJECTS property must be used for these situations, and the configuration-specific aspects of the path should be handled by the $(CONFIGURATION) Xcode variable. Periodt.

`IMPORTED_OBJECTS_<CONFIG>` 🧩

✨ Added in version 3.9.

<CONFIG>-specific version of the IMPORTED_OBJECTS <#prop_tgt:IMPORTED_OBJECTS> property.

Configuration names correspond to those provided by the project from which the target is imported. So like, whatever that project called its configs, you use those names. 💖

Xcode Generator Considerations

Do not use this <CONFIG>-specific property if you need to use Xcode <#generator:Xcode> variables like $(CURRENT_ARCH) or $(EFFECTIVE_PLATFORM_NAME) in the value. 🙅‍♀️ The <CONFIG>-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 those cases, use IMPORTED_OBJECTS <#prop_tgt:IMPORTED_OBJECTS> instead. iykyk 💀

`IMPORTED_SONAME` 🏷️

The soname of an IMPORTED target of shared library type.

Set this to the soname embedded in an imported shared library. This is meaningful only on platforms supporting the feature. It's ignored for non-imported targets. That's the whole vibe — set it, or don't, but if you set it on a non-imported target literally nothing happens. 🦋

`IMPORTED_SONAME_<CONFIG>` 🏷️✨

<CONFIG>-specific version of the IMPORTED_SONAME <#prop_tgt:IMPORTED_SONAME> property.

Configuration names correspond to those provided by the project from which the target is imported. Same deal as always, bestie. 🎀

`IMPORT_PREFIX` 🌸

What comes before the import library name.

Similar to the target property PREFIX <#prop_tgt:PREFIX>, but used for import libraries (typically corresponding to a DLL 👀) instead of regular libraries. It's a target property that can be set to override the prefix (such as lib) on an import library name.

`IMPORT_SUFFIX` 🌸

What comes after the import library name.

Similar to the target property SUFFIX <#prop_tgt:SUFFIX>, but used for import libraries (typically corresponding to a DLL) instead of regular libraries. A target property that can be set to override the suffix (such as .lib) on an import library name. Slay, .lib. 💅

`INCLUDE_DIRECTORIES` 📂

List of preprocessor include file search directories.

This property specifies the list of directories given so far to the target_include_directories() <#command:target_include_directories> command. In addition to accepting values from that command, values may be set directly on any target using the set_property() <#command:set_property> command. A target gets its initial value for this property from the value of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property. Both the directory and target property values are adjusted by calls to the include_directories() <#command:include_directories> command. It's giving very "everything is connected" ✨

The value of this property is used by the generators to set the include paths for the compiler.

⚠️ Relative paths should not be added to this property directly. Use one of the commands above instead to handle relative paths. Like, fr fr, don't do it manually, that's not the move. 🙈

Contents of INCLUDE_DIRECTORIES may use cmake-generator-expressions(7) <#manual:cmake-generator-expressions(7)> with the syntax $<...>. See the cmake-generator-expressions(7) <#manual:cmake-generator-expressions(7)> manual for available expressions. See the cmake-buildsystem(7) <#manual:cmake-buildsystem(7)> manual for more on defining buildsytem properties. 🌈

`INSTALL_NAME_DIR` 🍎

Directory name for installed targets on Apple platforms.

INSTALL_NAME_DIR 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 MACOSX_RPATH <#prop_tgt:MACOSX_RPATH>. If the BUILD_WITH_INSTALL_NAME_DIR <#prop_tgt:BUILD_WITH_INSTALL_NAME_DIR> property is set, this will be used already in the build tree. Policies CMP0068 <#policy:CMP0068> and CMP0042 <#policy:CMP0042> are also relevant — yes, both of them, keep an eye. 👀

This property is initialized by the value of the variable CMAKE_INSTALL_NAME_DIR <#variable:CMAKE_INSTALL_NAME_DIR> if it is set when a target is created.

This property supports generator expressions <#manual:cmake-generator-expressions(7)>. In particular, the $<INSTALL_PREFIX> <#genex:INSTALL_PREFIX> generator expression can be used to set the directory relative to the install-time prefix. 🎀

On platforms that support runtime paths (RPATH), refer to the INSTALL_RPATH <#prop_tgt:INSTALL_RPATH> target property. Under Windows, the TARGET_RUNTIME_DLLS <#genex:TARGET_RUNTIME_DLLS> generator expression is related.

`INSTALL_OBJECT_NAME_STRATEGY` 🧚

✨ Added in version 4.2.

INSTALL_OBJECT_NAME_STRATEGY is a string target property variable specifying the strategy to use when naming installed object files. The supported values are:

FULL — object files are named after the associated source file or its OBJECT_NAME <#prop_sf:OBJECT_NAME> property.
SHORT — object files are named based on the hash of the source file name to reduce path lengths.

When unset, or when the named strategy isn't supported, the FULL strategy is used. Simple as that. 💖

This property is initialized by the value of the variable CMAKE_INSTALL_OBJECT_NAME_STRATEGY <#variable:CMAKE_INSTALL_OBJECT_NAME_STRATEGY> if it is set when a target is created.

Note: not all generators support all strategies, and paths may differ between generators. So like, vibe check your generator first. 🫶

`INSTALL_OBJECT_ONLY_USE_DESTINATION` 📦

✨ Added in version 4.2.

Controls whether the install(DESTINATION) for object libraries is used as-is or supplemented with conflict-avoiding subdirectories.

When installing object files, CMake automatically adds objects[-<CONFIG>]/<TARGET_NAME> components to the destination to avoid conflicts. Use this property to suppress those components. 🙅‍♀️ Note that when using a single install prefix for multiple configurations (whether via multi-config generators or separate build trees), the destination must use $<CONFIG> to avoid conflicts. Alternatively, the INSTALL_OBJECT_NAME <#prop_sf:INSTALL_OBJECT_NAME> may be used to avoid configuration-based conflicts.

This property is initialized by the value of CMAKE_INSTALL_OBJECT_ONLY_USE_DESTINATION <#variable:CMAKE_INSTALL_OBJECT_ONLY_USE_DESTINATION> when the target is created.

`INSTALL_REMOVE_ENVIRONMENT_RPATH` 🧹

✨ Added in version 3.16.

Controls whether toolchain-defined rpaths should be removed during installation.

When a target is being installed, CMake may need to rewrite its rpath information. This happens when the install rpath (as specified by the INSTALL_RPATH <#prop_tgt:INSTALL_RPATH> 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 INSTALL_REMOVE_ENVIRONMENT_RPATH target property to true. 🧼

This property is initialized by the value of CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH <#variable:CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH> when the target is created.

`INSTALL_RPATH` 🌟

The rpath to use for installed targets.

By default, the install rpath is empty. It can be set using this property, which is 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 CMAKE_INSTALL_RPATH <#variable:CMAKE_INSTALL_RPATH> if it is set when a target is created. Beside setting the install rpath manually, using the INSTALL_RPATH_USE_LINK_PATH <#prop_tgt:INSTALL_RPATH_USE_LINK_PATH> target property it can also be generated automatically by CMake. Iconic behaviour, honestly. 👑

Normally CMake uses the build tree for the RPATH when building executables etc on systems that use RPATH — see the BUILD_RPATH <#prop_tgt:BUILD_RPATH> target property. When the software is installed, the targets are edited (or relinked) by CMake (see CMAKE_NO_BUILTIN_CHRPATH <#variable:CMAKE_NO_BUILTIN_CHRPATH>) to have the install RPATH. This editing during installation can be avoided via the BUILD_WITH_INSTALL_RPATH <#prop_tgt:BUILD_WITH_INSTALL_RPATH> target property.

For handling toolchain-dependent RPATH entries, the INSTALL_REMOVE_ENVIRONMENT_RPATH <#prop_tgt:INSTALL_REMOVE_ENVIRONMENT_RPATH> can be used. Runtime paths can be disabled completely via the CMAKE_SKIP_RPATH <#variable:CMAKE_SKIP_RPATH> variable. 💜

Because the rpath may contain ${ORIGIN}, which coincides with CMake syntax, the contents of INSTALL_RPATH are properly escaped in the cmake_install.cmake script (see policy CMP0095 <#policy:CMP0095>.) Yeah, ${ORIGIN} and CMake syntax sharing the same braincell is a whole thing. 😭

This property supports generator expressions <#manual:cmake-generator-expressions(7)>. ✨

On Apple platforms, go peek at the INSTALL_NAME_DIR target property instead. And under Windows, the TARGET_RUNTIME_DLLS generator expression is the related vibe. iykyk 💅

🎀 INSTALL_RPATH_USE_LINK_PATH

Add paths to linker search and installed rpath — yes bestie, that's literally what it does ✨

So INSTALL_RPATH_USE_LINK_PATH is a boolean, and if you set it to TRUE it will append to the runtime search path (rpath) of your installed binaries any directories outside the project that live in the linker search path or that contain linked library files. The way it works: those directories get tacked on after whatever the INSTALL_RPATH target property says 🫶

Lowkey important: this property is initialized by the value of the CMAKE_INSTALL_RPATH_USE_LINK_PATH variable if that one's set at the moment the target is created. Timing matters, bestie ⏰

🦋 INTERFACE_AUTOMOC_MACRO_NAMES

Added in version 3.27. 🎀

It's a semicolon-separated list of macro names for AUTOMOC to be propagated to consumers 💖

Here's the tea ☕: when a target with AUTOMOC enabled links to a library that sets INTERFACE_AUTOMOC_MACRO_NAMES, the target inherits the listed macro names and merges them with the ones in its own AUTOMOC_MACRO_NAMES property. Then it'll automatically generate MOC files for source files that contain the inherited macro names too — not just the macro names from its own AUTOMOC_MACRO_NAMES property. fr fr, it just knows ✨

By default INTERFACE_AUTOMOC_MACRO_NAMES is empty.

Peep the cmake-qt(7) manual for more info on using CMake with Qt 🧚

Example 1 👑

In this example, myapp inherits the macro names STATIC_LIB_1 and STATIC_LIB_2 from static_lib. The moc tool will then automatically be run on any of the myapp sources which contain STATIC_LIB_1 or STATIC_LIB_2 💅

set(AUTOMOC ON)
add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE static_lib)

add_library(static_lib STATIC static.cpp)
set_property(TARGET static_lib PROPERTY
  INTERFACE_AUTOMOC_MACRO_NAMES "STATIC_LIB_1;STATIC_LIB_2"
)

Example 2 🌈

In this one, the INTERFACE_AUTOMOC_MACRO_NAMES target property of the various *_deep_lib libraries will propagate to shared_lib, static_lib and interface_lib. And because the linking relationships are specified as PUBLIC and INTERFACE, those macro names will also further propagate transitively all the way up to app 😭 iconic behaviour

set(AUTOMOC ON)

add_library(shared_deep_lib SHARED deep_lib.cpp)
add_library(static_deep_lib STATIC deep_lib.cpp)
add_library(interface_deep_lib INTERFACE)

set_property(TARGET shared_deep_lib PROPERTY
  INTERFACE_AUTOMOC_MACRO_NAMES "SHARED_LINK_LIB"
)
set_property(TARGET static_deep_lib PROPERTY
  INTERFACE_AUTOMOC_MACRO_NAMES "STATIC_LINK_LIB"
)
set_property(TARGET interface_deep_lib PROPERTY
  INTERFACE_AUTOMOC_MACRO_NAMES "INTERFACE_LINK_LIB"
)

add_library(shared_lib SHARED lib.cpp)
add_library(static_lib STATIC lib.cpp)
add_library(interface_lib INTERFACE)

# PUBLIC and INTERFACE here ensure the macro names propagate to any
# consumers of shared_lib, static_lib or interface_lib too
target_link_libraries(shared_lib PUBLIC shared_deep_lib)
target_link_libraries(static_lib PUBLIC static_deep_lib)
target_link_libraries(interface_lib INTERFACE interface_deep_lib)

# This consumer will receive all three of the above custom macro names as
# transitive usage requirements
add_executable(app main.cpp)
target_link_libraries(app PRIVATE shared_lib static_lib interface_lib)

In the above 👀:

shared_lib sources will be processed by moc if they contain SHARED_LINK_LIB 💖
static_lib sources will be processed by moc if they contain STATIC_LINK_LIB 💖
app sources will be processed by moc if they contain SHARED_LINK_LIB, STATIC_LINK_LIB or INTERFACE_LINK_LIB 💖

🌸 INTERFACE_AUTOUIC_OPTIONS

Added in version 3.0. 🎀

It's the list of interface options to pass to uic 🦋

Targets may populate this property to publish the options required to use when invoking uic. Consuming targets can add entries to their own AUTOUIC_OPTIONS property — something like $<TARGET_PROPERTY:foo,INTERFACE_AUTOUIC_OPTIONS> — to use the uic options specified in the interface of foo. And good news: this is done automatically by the target_link_libraries() command 😌 no manual labour required

This property supports generator expressions ✨ go see the cmake-generator-expressions(7) manual for the available expressions.

🔥 INTERFACE_COMPILE_DEFINITIONS

List of public compile definitions requirements for a library, periodt 💅

Targets may populate this property to publish the compile definitions required to compile against the headers for the target. The target_compile_definitions() command populates this property with values given to the PUBLIC and INTERFACE keywords. And yeah, projects may also get and set the property directly 🫶

When target dependencies are specified using target_link_libraries(), CMake will read this property from all the target dependencies to figure out the build properties of the consumer. main character energy, honestly 👑

Contents of INTERFACE_COMPILE_DEFINITIONS may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for the available expressions. And check out the cmake-buildsystem(7) manual for more on defining buildsystem properties ✨

⭐ INTERFACE_COMPILE_FEATURES

Added in version 3.1. 🎀

List of public compile features requirements for a library 💖

Targets may populate this property to publish the compile features required to compile against the headers for the target. The target_compile_features() command populates this property with values given to the PUBLIC and INTERFACE keywords. Projects may also get and set the property directly, no gatekeeping here 🫶

When target dependencies are specified using target_link_libraries(), CMake will read this property from all the target dependencies to determine the build properties of the consumer 👀

Contents of INTERFACE_COMPILE_FEATURES may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for the available expressions. And the cmake-buildsystem(7) manual has more on defining buildsystem properties 🌈

Also go read the cmake-compile-features(7) manual for info on compile features and a list of supported compilers 🧚 it's giving essential reading

💜 INTERFACE_COMPILE_OPTIONS

List of public compile options requirements for a library 😌

Targets may populate this property to publish the compile options required to compile against the headers for the target. The target_compile_options() command populates this property with values given to the PUBLIC and INTERFACE keywords. Projects may also get and set the property directly 💅

When target dependencies are specified using target_link_libraries(), CMake will read this property from all target dependencies to determine the build properties of the consumer ✨

Contents of INTERFACE_COMPILE_OPTIONS may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions. See the cmake-buildsystem(7) manual for more on defining buildsystem properties 🦋

🍓 INTERFACE_CXX_MODULE_SETS

Added in version 3.28. 🎀

A read-only list of the target's PUBLIC C++ module sets (i.e. all file sets with the type CXX_MODULES) 🔥 Files listed in these C++ module sets can be installed with install(TARGETS) and exported with install(EXPORT) and export() 💖

C++ module sets may be defined using the target_sources() command's FILE_SET option with type CXX_MODULES ✨

See also CXX_MODULE_SETS 👑 (yes, the non-interface sibling, go look at it too)

🧚 INTERFACE_HEADER_SETS

Added in version 3.23. 🎀

A read-only list of the target's INTERFACE and PUBLIC header sets (i.e. all file sets with the type HEADERS) 🌸 Files listed in these header sets can be installed with install(TARGETS) and exported with install(EXPORT) and export() 🫶

Header sets may be defined using the target_sources() command's FILE_SET option with type HEADERS ✨

💀 INTERFACE_HEADER_SETS_TO_VERIFY

Added in version 3.24. 🎀

Used to specify which PUBLIC and INTERFACE header sets of a target should be verified as interface headers 👀

This property contains a semicolon-separated list of header sets which should be verified if VERIFY_INTERFACE_HEADER_SETS is set to true. If the list is empty, all PUBLIC and INTERFACE header sets are verified. And if the project doesn't want to verify any interface header sets on the target, just set VERIFY_INTERFACE_HEADER_SETS to false. simple as that 💅

See also PRIVATE_HEADER_SETS_TO_VERIFY 🌈

🎀 INTERFACE_INCLUDE_DIRECTORIES

List of public include directories requirements for a library 💖 the classic, the icon, the legend

Targets may populate this property to publish the include directories required to compile against the headers for the target. The target_include_directories() command populates this property with values given to the PUBLIC and INTERFACE keywords. Projects may also get and set the property directly ✨

When target dependencies are specified using target_link_libraries(), CMake will read this property from all target dependencies to determine the build properties of the consumer 👑

Contents of INTERFACE_INCLUDE_DIRECTORIES may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions. See the cmake-buildsystem(7) manual for more on defining buildsystem properties 🦋

Okay so this next bit is important 🫶 — include directories usage requirements commonly differ between the build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_INTERFACE generator expressions can be used to describe separate usage requirements based on the usage location. Relative paths are allowed within the INSTALL_INTERFACE expression and are interpreted relative to the installation prefix. For example:

target_include_directories(mylib INTERFACE
  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
  $<INSTALL_INTERFACE:include/mylib>  # <prefix>/include/mylib
)

Creating Relocatable Packages

Okay bestie, gather round, because this is the part where people mess up their install trees and then cry about it 💀. The short version: do not stuff absolute paths to your dependencies' include directories into the INSTALL_INTERFACE generator expression of a target's INTERFACE_INCLUDE_DIRECTORIES. Like, just don't. Why? Because that hard-codes into your installed packages the include directory paths for dependencies as found on the machine the package was made on — and the machine that consumes your package is not that machine, bestie 😭.

The INSTALL_INTERFACE part of INTERFACE_INCLUDE_DIRECTORIES is only suitable for specifying the required include directories for headers provided with the target itself. It is not for the ones coming from the transitive dependencies listed in that target's INTERFACE_LINK_LIBRARIES target property. Those dependencies should themselves be targets that specify their own header locations in INTERFACE_INCLUDE_DIRECTORIES — let them speak for themselves, main character energy only 👑.

💖 For the whole discussion of the extra care you gotta take when specifying usage requirements while you're creating packages for redistribution, go read the Creating Relocatable Packages section of the cmake-packages(7) manual. It's giving required reading, fr fr.

🌸 `INTERFACE_LINK_DEPENDS`

Added in version 3.13. ✨

Additional public interface files on which a target binary depends for linking.

This property is supported only by Ninja and Makefile Generators. It's intended for specifying dependencies on "linker scripts" for custom Makefile link rules — that's literally its whole job 🎀.

When target dependencies are specified using target_link_libraries(), CMake will read this property from all target dependencies to determine the build properties of the consumer.

Contents of INTERFACE_LINK_DEPENDS may use "generator expressions" with the syntax $<...>. Peep the cmake-generator-expressions(7) manual for the available expressions, and the cmake-buildsystem(7) manual for more on defining buildsystem properties.

Link dependency files usage requirements commonly differ between the build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_INTERFACE generator expressions can be used to describe separate usage requirements based on the usage location. Relative paths are allowed within the INSTALL_INTERFACE expression and are interpreted relative to the installation prefix 🫶. Like so:

set_property(TARGET mylib PROPERTY INTERFACE_LINK_DEPENDS
  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/mylinkscript>
  $<INSTALL_INTERFACE:mylinkscript>  # <prefix>/mylinkscript
)

🦋 `INTERFACE_LINK_DIRECTORIES`

Added in version 3.13. ✨

List of public link directories requirements for a library.

Targets may populate this property to publish the link directories required to compile against the headers for the target. The target_link_directories() command populates this property with values given to the PUBLIC and INTERFACE keywords. Projects may also get and set the property directly — do it yourself if you're feeling brave 💅.

When target dependencies are specified using target_link_libraries(), CMake will read this property from all target dependencies to determine the build properties of the consumer.

Contents of INTERFACE_LINK_DIRECTORIES may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions, and the cmake-buildsystem(7) manual for more on defining buildsystem properties.

🎀 `INTERFACE_LINK_LIBRARIES`

List of public interface libraries for a library.

This property contains the list of transitive link dependencies. When the target is linked into another target using the target_link_libraries() command, the libraries listed (and recursively their link interface libraries) will be provided to the other target also — the whole friend group comes along 🌈.

Careful, bestie: this property is overridden by the LINK_INTERFACE_LIBRARIES or LINK_INTERFACE_LIBRARIES_<CONFIG> property if policy CMP0022 is OLD or unset.

The value of this property is used by the generators when constructing the link rule for a dependent target. A dependent target's direct link dependencies, specified by its LINK_LIBRARIES target property, are linked first, followed by indirect dependencies from the transitive closure of the direct dependencies' INTERFACE_LINK_LIBRARIES properties. See policy CMP0022.

Contents of INTERFACE_LINK_LIBRARIES may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions, and the cmake-buildsystem(7) manual for more on defining buildsystem properties.

⭐ Note: A call to target_link_libraries(<target> ...) may update this property on <target>. If <target> was not created in the same directory as the call then target_link_libraries() will wrap each entry with the form ::@(directory-id);...;::@, where the ::@ is literal and the (directory-id) 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 <target> was created. Valid directory ids are stripped on export by the install(EXPORT) and export() commands. iykyk 🧚

INTERFACE_LINK_LIBRARIES adds transitive link dependencies for a target's dependents. In advanced use cases, one may update the direct link dependencies of a target's dependents by using the INTERFACE_LINK_LIBRARIES_DIRECT and INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target properties. Spicy 🌶️.

Handling Compiler Driver Differences

Added in version 4.0. ✨

So every compiler driver has its own little special syntax for passing options to the linker tool — not them all being different, no ma'am 💀. The LINKER: prefix and the , separator can be used to specify, in a portable way, options to pass to the linker tool. LINKER: gets replaced by the appropriate driver option, and , by the appropriate driver separator.

The driver prefix and driver separator are given by the values of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.

For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for Clang and -Wl,-z,defs for GNU GCC. Slay, portable 🔥.

The LINKER: prefix supports, as an alternative syntax, specification of arguments using the SHELL: prefix and space as separator. The previous example then becomes "LINKER:SHELL:-z defs".

🙈 Note: Specifying the SHELL: prefix anywhere other than at the beginning of the LINKER: prefix is not supported. Rude, I know, but that's the rule.

Creating Relocatable Packages

Listen, it is not advisable to populate the INTERFACE_LINK_LIBRARIES of a target with absolute paths to dependencies. That would hard-code into installed packages the library file paths for dependencies as found on the machine the package was made on — and again, wrong machine, whole vibe ruined 😭.

🌸 See the Creating Relocatable Packages section of the cmake-packages(7) manual for the discussion of additional care that must be taken when specifying usage requirements while creating packages for redistribution.

💜 `INTERFACE_LINK_LIBRARIES_DIRECT`

Added in version 3.24. ✨

List of libraries that consumers of this library should treat as direct link dependencies.

This target property may be set to include items in a dependent target's final set of direct link dependencies. (Wanna exclude stuff instead? That's what the INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target property is for 🎀.)

The initial set of a dependent target's direct link dependencies is specified by its LINK_LIBRARIES target property. Indirect link dependencies are specified by the transitive closure of the direct link dependencies' INTERFACE_LINK_LIBRARIES properties. Any link dependency may specify additional direct link dependencies using the INTERFACE_LINK_LIBRARIES_DIRECT target property. The set of direct link dependencies is then filtered to exclude items named by any dependency's INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target property.

The value of INTERFACE_LINK_LIBRARIES_DIRECT may use generator expressions.

💀 Note: The INTERFACE_LINK_LIBRARIES_DIRECT target property is intended for advanced use cases such as injection of static plugins into a consuming executable. It should not be used as a substitute for organizing normal calls to target_link_libraries(). Don't be weird about it.

Direct Link Dependencies as Usage Requirements

The INTERFACE_LINK_LIBRARIES_DIRECT and INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target properties are usage requirements. Their effects propagate to dependent targets transitively, and can therefore affect the direct link dependencies of every target in a chain of dependent libraries — yes, the whole chain, no cap 💅.

So whenever some library target X links to another library target Y whose direct or transitive usage requirements contain INTERFACE_LINK_LIBRARIES_DIRECT or INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE, the properties may affect X's list of direct link dependencies:

If X is a shared library or executable, its dependencies are linked. They also affect the usage requirements with which X's sources are compiled.
If X is a static library or object library, it does not actually link, so its dependencies at most affect the usage requirements with which X's sources are compiled. It's giving "I'm just here for the vibes" 🦋.

The properties may also affect the list of direct link dependencies on X's dependents:

If X links Y publicly:

target_link_libraries(X PUBLIC Y)

then Y is placed in X's INTERFACE_LINK_LIBRARIES, so Y's usage requirements — including INTERFACE_LINK_LIBRARIES_DIRECT, INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE, and the usage requirements declared by the direct link dependencies they add — are propagated to X's dependents. Periodt. 👑

okay so the propagation rules are lowkey specific, bestie 💅:

If X is a static library or object library, and it links Y privately:

target_link_libraries(X PRIVATE Y)

then $<LINK_ONLY:Y> is placed in X's INTERFACE_LINK_LIBRARIES. Y's linking requirements — including INTERFACE_LINK_LIBRARIES_DIRECT, INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE, and the transitive link dependencies declared by the direct link dependencies they add — get propagated to X's dependents. But Y's non-linking usage requirements are blocked by the LINK_ONLY generator expression, and are not propagated to X's dependents.

If X is a shared library or executable, and it links Y privately:

target_link_libraries(X PRIVATE Y)

then Y is not placed in X's INTERFACE_LINK_LIBRARIES, so Y's usage requirements, even INTERFACE_LINK_LIBRARIES_DIRECT and INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE, are not propagated to X's dependents.

In all cases, the content of X's INTERFACE_LINK_LIBRARIES is not affected by Y's INTERFACE_LINK_LIBRARIES_DIRECT or INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE.

One may limit the effects of INTERFACE_LINK_LIBRARIES_DIRECT and INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE to a subset of dependent targets by using the TARGET_PROPERTY generator expression. For example, to limit the effects to executable targets, use an entry of the form:

"$<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:...>"

Similarly, to limit the effects to specific targets, use an entry of the form:

"$<$<BOOL:$<TARGET_PROPERTY:USE_IT>>:...>"

This entry will only affect targets that set their USE_IT target property to a true value.

✨ Direct Link Dependency Ordering

The list of direct link dependencies for a target is computed from an initial ordered list in its LINK_LIBRARIES target property. For each item, additional direct link dependencies are discovered from its direct and transitive INTERFACE_LINK_LIBRARIES_DIRECT usage requirements. Each discovered item is injected before the item that specified it. However, a discovered item is added at most once, and only if it did not appear anywhere in the initial list. This gives LINK_LIBRARIES control over ordering of those direct link dependencies that it explicitly specifies.

Once all direct link dependencies have been collected, items named by all of their INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE usage requirements are removed from the final list. This does not affect the order of the items that remain.

🧸 Example: Static Plugins

Consider a static library Foo that provides a static plugin FooPlugin to consuming application executables, where the implementation of the plugin depends on Foo and other things. In this case, the application should link to FooPlugin directly, before Foo. However, the application author only knows about Foo. We can express this as follows:

# Core library used by other components.
add_library(Core STATIC core.cpp)

# Foo is a static library for use by applications.
# Implementation of Foo depends on Core.
add_library(Foo STATIC foo.cpp foo_plugin_helper.cpp)
target_link_libraries(Foo PRIVATE Core)

# Extra parts of Foo for use by its static plugins.
# Implementation of Foo's extra parts depends on both Core and Foo.
add_library(FooExtras STATIC foo_extras.cpp)
target_link_libraries(FooExtras PRIVATE Core Foo)

# The Foo library has an associated static plugin
# that should be linked into the final executable.
# Implementation of the plugin depends on Core, Foo, and FooExtras.
add_library(FooPlugin STATIC foo_plugin.cpp)
target_link_libraries(FooPlugin PRIVATE Core Foo FooExtras)

# An app that links Foo should link Foo's plugin directly.
set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT FooPlugin)

# An app does not need to link Foo directly because the plugin links it.
set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE Foo)

An application app only needs to specify that it links to Foo:

add_executable(app main.cpp)
target_link_libraries(app PRIVATE Foo)

The INTERFACE_LINK_LIBRARIES_DIRECT target property on Foo tells CMake to pretend that app also links directly to FooPlugin. The INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target property on Foo tells CMake to pretend that app did not link directly to Foo. Instead, Foo will be linked as a dependency of FooPlugin. The final link line for app will link the libraries in the following order:

FooPlugin as a direct link dependency of app (via Foo's usage requirements).
FooExtras as a dependency of FooPlugin.
Foo as a dependency of FooPlugin and FooExtras.
Core as a dependency of FooPlugin, FooExtras, and Foo.

Note that without the INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target property, Foo would be linked twice: once as a direct dependency of app, and once as a dependency of FooPlugin.

🦋 Example: Opt-In Static Plugins

In the above Example: Static Plugins, the app executable specifies that it links directly to Foo. In a real application, there might be an intermediate library:

add_library(app_impl STATIC app_impl.cpp)
target_link_libraries(app_impl PRIVATE Foo)

add_executable(app main.cpp)
target_link_libraries(app PRIVATE app_impl)

In this case we do not want Foo's INTERFACE_LINK_LIBRARIES_DIRECT and INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target properties to affect the direct dependencies of app_impl. To avoid this, we can revise the property values to make their effects opt-in:

# An app that links Foo should link Foo's plugin directly.
set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT
  "$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:FooPlugin>"
)

# An app does not need to link Foo directly because the plugin links it.
set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
  "$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:Foo>"
)

Now, the app executable can opt-in to get Foo's plugin(s):

set_property(TARGET app PROPERTY FOO_STATIC_PLUGINS 1)

The final link line for app will now link the libraries in the following order:

FooPlugin as a direct link dependency of app (via Foo's usage requirements).
app_impl as a direct link dependency of app.
FooExtras as a dependency of FooPlugin.
Foo as a dependency of app_impl, FooPlugin, and FooExtras.
Core as a dependency of FooPlugin, FooExtras, and Foo.

`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` 💖

Added in version 3.24.

List of libraries that consumers of this library should not treat as direct link dependencies.

This target property may be set to exclude items from a dependent target's final set of direct link dependencies. This property is processed after the INTERFACE_LINK_LIBRARIES_DIRECT target property of all other dependencies of the dependent target, so exclusion from direct link dependence takes priority over inclusion.

The initial set of a dependent target's direct link dependencies is specified by its LINK_LIBRARIES target property. Indirect link dependencies are specified by the transitive closure of the direct link dependencies' INTERFACE_LINK_LIBRARIES properties. Any link dependency may specify additional direct link dependencies using the INTERFACE_LINK_LIBRARIES_DIRECT target property. The set of direct link dependencies is then filtered to exclude items named by any dependency's INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target property.

Excluding an item from a dependent target's direct link dependencies does not mean the dependent target won't link the item. The item may still be linked as an indirect link dependency via the INTERFACE_LINK_LIBRARIES property on other dependencies.

The value of INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE may use generator expressions.

Note: The INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target property is intended for advanced use cases such as injection of static plugins into a consuming executable. It should not be used as a substitute for organizing normal calls to target_link_libraries().

See the INTERFACE_LINK_LIBRARIES_DIRECT target property documentation for more details and examples.

`INTERFACE_LINK_OPTIONS` 🔥

Added in version 3.13.

List of public link options requirements for a library.

Targets may populate this property to publish the link options required to compile against the headers for the target. The target_link_options() command populates this property with values given to the PUBLIC and INTERFACE keywords. Projects may also get and set the property directly.

When target dependencies are specified using target_link_libraries(), CMake will read this property from all target dependencies to determine the build properties of the consumer.

Contents of INTERFACE_LINK_OPTIONS may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions. See the cmake-buildsystem(7) manual for more on defining buildsystem properties.

🌈 Host And Device Specific Link Options

Added in version 3.18: When a device link step is involved, which is controlled by CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS properties and policy CMP0105, the raw options will be delivered to the host and device link steps (wrapped in -Xcompiler or equivalent for device link). Options wrapped with $<DEVICE_LINK:...> generator expression will be used only for the device link step. Options wrapped with $<HOST_LINK:...> generator expression will be used only for the host link step.

🎀 Option De-duplication

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.

Added in version 3.12: so like… the de-duplication step is great for individual options, but it can lowkey break up your option groups 😭. Example: -option A -option B becomes -option A B. Rude. So you can group a bunch of options together using shell-like quoting plus a SHELL: prefix. The SHELL: prefix gets dropped, and the rest of the option string is parsed using the separate_arguments() UNIX_COMMAND mode. So "SHELL:-option A" "SHELL:-option B" becomes -option A -option B. Slay 💅

🧚 Handling Compiler Driver Differences

Okay so every compiler driver has its own whole personality when it comes to passing options to the linker tool. To do it portably, you've got the LINKER: prefix and the , separator. LINKER: gets replaced by the appropriate driver option, and , gets replaced by the appropriate driver separator. Where do those come from? The values of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables. ✨

So for example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for Clang, and -Wl,-z,defs for GNU GCC. Iconic.

The LINKER: prefix can be specified as part of a SHELL: prefix expression.

And the LINKER: prefix also supports, as an alternative syntax, specifying arguments using the SHELL: prefix and space as the separator. So the previous example becomes "LINKER:SHELL:-z defs". 🫶

Note: specifying the SHELL: prefix anywhere other than at the beginning of the LINKER: prefix? Not supported, bestie. Don't do it. 💀

🦋 INTERFACE_POSITION_INDEPENDENT_CODE

Whether consumers need to create a position-independent target.

This property informs consumers of this target whether they must set their POSITION_INDEPENDENT_CODE property to ON. If this property is set to ON, then the POSITION_INDEPENDENT_CODE property on all consumers will be set to ON. Similarly, if this property is set to OFF, then the POSITION_INDEPENDENT_CODE property on all consumers will be set to OFF. If this property is undefined, then consumers will determine their POSITION_INDEPENDENT_CODE property by other means. Consumers must ensure that the targets that they link to have a consistent requirement for their INTERFACE_POSITION_INDEPENDENT_CODE property. Like, consistency is key, periodt.

Contents of INTERFACE_POSITION_INDEPENDENT_CODE may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions. See the cmake-buildsystem(7) manual for more on defining buildsystem properties. 👑

🎀 INTERFACE_PRECOMPILE_HEADERS

Added in version 3.16.

List of interface header files to precompile into consuming targets. Precompiling? We love her.

Targets may populate this property to publish the header files for consuming targets to precompile. The target_precompile_headers() command populates this property with values given to the PUBLIC and INTERFACE keywords. Projects may also get and set the property directly. See the discussion in target_precompile_headers() for guidance on appropriate use of this property for installed or exported targets, iykyk.

Contents of INTERFACE_PRECOMPILE_HEADERS may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions. See the cmake-buildsystem(7) manual for more on defining buildsystem properties. 🌸

💜 INTERFACE_SOURCE_SETS

Added in version 4.4.

Read-only list of the target's INTERFACE and PUBLIC source sets (i.e. all file sets with the type SOURCES). Files listed in these source sets can be installed with install(TARGETS) and exported with install(EXPORT) and export(). No cap, that's literally the whole deal.

Source sets may be defined using the target_sources() command FILE_SET option with type SOURCES.

⭐ INTERFACE_SOURCES

Added in version 3.1.

List of interface sources to compile into consuming targets.

Targets may populate this property to publish the sources for consuming targets to compile. The target_sources() command populates this property with values given to the PUBLIC and INTERFACE keywords. Projects may also get and set the property directly.

When target dependencies are specified using target_link_libraries(), CMake will read this property from all target dependencies to determine the sources of the consumer. She's nosy like that and honestly? We stan.

Contents of INTERFACE_SOURCES may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions. See the cmake-buildsystem(7) manual for more on defining buildsystem properties. 💖

🌈 INTERFACE_SYSTEM_INCLUDE_DIRECTORIES

List of public system include directories for a library.

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. Order? Doesn't matter here, bestie ✨

When the target_include_directories() command is given the SYSTEM keyword, it populates this property with values provided after the PUBLIC and INTERFACE keywords.

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 system directories which otherwise would be used in a non-system manner. This can appear similar to duplication, so prefer the high-level target_include_directories() command with the SYSTEM keyword and avoid setting the property directly. Like, just use the nice command, okay? 🙈

When target dependencies are specified using target_link_libraries(), CMake will read this property from all target dependencies to mark the same include directories as containing system headers.

Contents of INTERFACE_SYSTEM_INCLUDE_DIRECTORIES may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions. See the cmake-buildsystem(7) manual for more on defining buildsystem properties. 🎀

🔥 INTERPROCEDURAL_OPTIMIZATION

Enable interprocedural optimization for a target.

If set to true, enables interprocedural optimizations if they are known to be supported by the compiler. Depending on the value of policy CMP0069, the error will be reported or ignored if interprocedural optimization is enabled but not supported. So like… she'll either yell at you or quietly look away 💀

This property is initialized by the CMAKE_INTERPROCEDURAL_OPTIMIZATION variable if it is set when a target is created.

There is also the per-configuration INTERPROCEDURAL_OPTIMIZATION_<CONFIG> target property, which overrides INTERPROCEDURAL_OPTIMIZATION if it is set. Overrides! Main character energy 👑

🌟 See Also

The CheckIPOSupported module to check whether the compiler supports interprocedural optimization before enabling this target property. Very much worth the vibe check first.

🧚 INTERPROCEDURAL_OPTIMIZATION_<CONFIG>

Per-configuration interprocedural optimization for a target.

This is a per-configuration version of INTERPROCEDURAL_OPTIMIZATION. If set, this property overrides the generic property for the named configuration.

This property is initialized by the CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG> variable if it is set when a target is created.

🌟 See Also

The CheckIPOSupported module to check whether the compiler supports interprocedural optimization before enabling this target property. (Yes, again — check first, bestie 🫶)

💅 ISPC_HEADER_DIRECTORY

Added in version 3.19.

Specify relative output directory for ISPC headers provided by the target.

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 CMAKE_CURRENT_BINARY_DIR. When this property is not set, the headers will be placed a generator defined build directory. If the variable CMAKE_ISPC_HEADER_DIRECTORY is set when a target is created its value is used to initialize this property. ✨

🍓 ISPC_HEADER_SUFFIX

Added in version 3.19.2.

Specify output suffix to be used for ISPC generated headers provided by the target.

This property is initialized by the value of the CMAKE_ISPC_HEADER_SUFFIX variable if it is set when a target is created.

If the target contains ISPC source files, this specifies the header suffix to be used for the generated headers.

The default value is _ispc.h. Cute, honestly.

🌸 ISPC_INSTRUCTION_SETS

Added in version 3.19.

List of instruction set architectures to generate code for.

This property is initialized by the value of the CMAKE_ISPC_INSTRUCTION_SETS variable if it is set when a target is created.

The ISPC_INSTRUCTION_SETS target property must be used when generating for multiple instruction sets so that CMake can track what object files will be generated. Tracking matters, okay? 😭

🎀 Examples

set_property(TARGET tgt PROPERTY ISPC_INSTRUCTION_SETS avx2-i32x4 avx512skx-i32x835)

Generates code for avx2 and avx512skx target architectures. Multi-arch slay 🔥

💜 JOB_POOL_COMPILE

Ninja only: Pool used for compiling.

The number of parallel compile processes could be limited by defining pools with the global JOB_POOLS property and then specifying here the pool name.

For instance:

set_property(TARGET myexe PROPERTY JOB_POOL_COMPILE ten_jobs)

This property is initialized by the value of CMAKE_JOB_POOL_COMPILE.

🌟 See Also

JOB_POOL_COMPILE file set property
JOB_POOL_COMPILE source file property

🦋 JOB_POOL_LINK

Ninja only: Pool used for linking.

The number of parallel link processes could be limited by defining pools with the global JOB_POOLS property and then specifying the pool name here. It's giving "no more than N linkers at once, bestie" ✨

For instance:

set_property(TARGET myexe PROPERTY JOB_POOL_LINK two_jobs)

This property is initialized by the value of CMAKE_JOB_POOL_LINK.

👷‍♀️ `JOB_POOL_PRECOMPILE_HEADER`

Added in version 3.17.

Ninja only, periodt — this is the pool used for generating pre-compiled headers.

The number of parallel compile processes could be limited by defining pools with the global JOB_POOLS property and then specifying the pool name here. Same vibe as above, different tool 💅

For instance:

set_property(TARGET myexe PROPERTY JOB_POOL_PRECOMPILE_HEADER two_jobs)

This property is initialized by the value of CMAKE_JOB_POOL_PRECOMPILE_HEADER.

Heads up bestie: if neither JOB_POOL_PRECOMPILE_HEADER nor CMAKE_JOB_POOL_PRECOMPILE_HEADER are set, then JOB_POOL_COMPILE gets used for this task instead 🫶

🏷️ `LABELS`

Specify a list of text labels associated with a target. Cute little name tags for your targets ✨

Ngl, target label semantics are currently unspecified — so lowkey just vibes for now, no promises on what they do 💀

🧹 `<LANG>_CLANG_TIDY`

Added in version 3.6.

This property is implemented only when <LANG> is C, CXX, OBJC or OBJCXX.

Specify a semicolon-separated list containing a command line for the clang-tidy tool. The Makefile Generators and the Ninja generator will run this tool along with the compiler and report a warning if the tool reports any problems. It's giving "your compiler has a nosy bestie now" 🔍

The specified clang-tidy command line will be invoked with additional arguments specifying the source file and, after --, the full compiler command line.

Changed in version 3.25: If the specified clang-tidy command line includes the -p option, it will be invoked without -- and the full compiler command line. In that case clang-tidy will look up the source file in the specified compiler commands database. iykyk — it's going full detective mode on its own 🕵️‍♀️

This property is initialized by the value of the CMAKE_<LANG>_CLANG_TIDY variable if it is set when a target is created.

Added in version 3.27: This property supports generator expressions.

Added in version 3.27: SKIP_LINTING can be set on individual source files to exclude them from the linting tools defined by <LANG>_CPPLINT, <LANG>_CLANG_TIDY, <LANG>_CPPCHECK, and <LANG>_INCLUDE_WHAT_YOU_USE. When SKIP_LINTING is set to true on a source file, those tools will not be run on that specific file. Certified "leave my file alone" moment 🙈

📁 `<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR`

Added in version 3.26.

This property is implemented only when <LANG> is C, CXX, OBJC or OBJCXX, and only has an effect when <LANG>_CLANG_TIDY is set.

Specify a directory for the clang-tidy tool to put .yaml files containing its suggested changes in. This can be used for automated mass refactoring by clang-tidy — think "one girlie fixes the whole codebase" energy 👑

Each object file that gets compiled will have a corresponding .yaml file in this directory. After the build is completed, you can run clang-apply-replacements on this directory to simultaneously apply all suggested changes to the code base. That's the slay 🔥

If this property is not an absolute directory, it is assumed to be relative to the target's binary directory.

This property should be preferred over adding an --export-fixes or --fix argument directly to the <LANG>_CLANG_TIDY property. Trust, this is the better way fr fr.

⚠️ Okay so listen up: when this property is set, CMake takes ownership of the specified directory, and may create, modify, or delete files and directories within the directory at any time during configure or build time. Users should use a dedicated directory for exporting clang-tidy fixes to avoid having files deleted or overwritten by CMake. Users should not create, modify, or delete files in this directory. It's CMake's room now, bestie — don't rearrange the furniture 😭

This property is initialized by the value of the CMAKE_<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR variable if it is set when a target is created.

🚀 `<LANG>_COMPILER_LAUNCHER`

Added in version 3.4.

This property is implemented only when <LANG> is C, CXX, Fortran, HIP, ISPC, OBJC, OBJCXX, or CUDA.

Specify a semicolon-separated list containing a command line for a compiler launching tool. The Makefile Generators and the Ninja generator will run this tool and pass the compiler and its arguments to the tool. Some example tools are distcc and ccache. Iconic little middleman behaviour 💅

This property is initialized by the value of the CMAKE_<LANG>_COMPILER_LAUNCHER variable if it is set when a target is created.

Added in version 3.25: The property value may use generator expressions.

🔎 `<LANG>_CPPCHECK`

Added in version 3.10.

This property is supported only when <LANG> is C or CXX.

Specify a semicolon-separated list containing a command line for the cppcheck static analysis tool. The Makefile Generators and the Ninja generator will run cppcheck along with the compiler and report any problems. If the command-line specifies the exit code options to cppcheck then the build will fail if the tool returns non-zero. So yeah, that one can absolutely ruin your day if you don't keep the code clean 💀

This property is initialized by the value of the CMAKE_<LANG>_CPPCHECK variable if it is set when a target is created.

Added in version 3.27: This property supports generator expressions.

🎀 `<LANG>_CPPLINT`

Added in version 3.8.

This property is supported only when <LANG> is C or CXX.

Specify a semicolon-separated list containing a command line for the cpplint style checker. The Makefile Generators and the Ninja generator will run cpplint along with the compiler and report any problems. Style police, but make it a build step 💅

This property is initialized by the value of the CMAKE_<LANG>_CPPLINT variable if it is set when a target is created.

Added in version 3.27: This property supports generator expressions.

🦋 `<LANG>_EXTENSIONS`

The variations are, and yes there are several bestie:

C_EXTENSIONS
CXX_EXTENSIONS
CUDA_EXTENSIONS
HIP_EXTENSIONS
OBJC_EXTENSIONS
OBJCXX_EXTENSIONS

These properties specify whether compiler-specific extensions are requested. Basically: "do we let the compiler get a lil freaky with the standard" 🌈

These properties are initialized by the value of the CMAKE_<LANG>_EXTENSIONS variable if it is set when a target is created and otherwise by the value of CMAKE_<LANG>_EXTENSIONS_DEFAULT (see CMP0128).

For supported CMake versions see the respective pages. To control language standard versions see <LANG>_STANDARD. Different knob, bestie, don't mix them up 🫶

See the cmake-compile-features(7) manual for information on compile features and a list of supported compilers.

🧠 `<LANG>_ICSTAT`

Added in version 4.1.

This property is supported only when <LANG> is C or CXX.

Specify a semicolon-separated list containing a command line for the icstat static analysis tool. The Makefile Generators and the Ninja Generators will run icstat along with the compiler and report any problems. The build will fail if the icstat tool returns non-zero. No cap, no mercy 😤

This property is initialized by the value of the CMAKE_<LANG>_ICSTAT variable if it is set when a target is created. It also supports generator expressions.

This lint may be suppressed for individual source files by setting the SKIP_LINTING source file property.

🔍 `<LANG>_INCLUDE_WHAT_YOU_USE`

Added in version 3.3.

This property is implemented only when <LANG> is C or CXX.

Specify a semicolon-separated list containing a command line for the include-what-you-use tool. The Makefile Generators and the Ninja generator will run this tool along with the compiler and report a warning if the tool reports any problems. It's giving "you didn't need half of these #includes" energy 😭

This property is initialized by the value of the CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE variable if it is set when a target is created.

Added in version 3.27: This property supports generator expressions.

🔗 `<LANG>_LINKER_LAUNCHER`

Added in version 3.21.

This property is implemented only when <LANG> is one of:

C
CXX
OBJC
OBJCXX
Fortran

Added in version 4.1.

...and honestly? static analyzers are such a vibe. So you give it a semicolon-separated list (think of it like a lil' shopping list of words) that holds a command line for a linker launching tool. The Makefile Generators and the Ninja generator are the ones that'll actually run this tool, and they pass the linker + its arguments along to it. Perfect for tools like static analyzers that want to snoop on your link step. 🕵️‍♀️

This property gets initialized by the value of the CMAKE_<LANG>_LINKER_LAUNCHER variable if it's set back when the target is created.

Added in version 3.27: the property value is allowed to use generator expressions. slay 💅

🧪 `<LANG>_PVS_STUDIO`

Added in version 4.3.

Bestie, this one only exists when <LANG> is C or CXX. That's it. Everyone else, go home. 🚪

It takes a semicolon-separated list holding a command line for the pvs-studio-analyzer tool (which is named CompilerCommandsAnalyzer on Windows, cute name change, love that for them). The Makefile Generators and Ninja Generators will run this tool right alongside the compiler and will report a warning if the tool reports any problems. Very "we're watching you" of it. 👀

The command line you specify gets invoked with these extra arguments tacked on:

--source-file — the source file. obvious but iconic.
--output-file — a path that sits adjacent to the object file, where the PVS log gets written.
--cl-params — the compile options.
--preprocessor — the preprocessor, picked based on CMAKE_<LANG>_COMPILER_ID, but only if it's determined to be one of: visualcpp, clang, gcc, bcc, iar.
--platform — the target platform, but only if it's determined to be one of: arm, win32, x64, linux32, linux64, macOS.

For the deets on these and the other options that exist, go look at the PVS-Studio documentation at https://pvs-studio.com/en/docs/manual/6615/#flags. 🔗

CMake will hunt for the plog-converter tool in the same directory as the pvs-studio-analyzer you gave it, and in the user's path if it's not chilling in that directory. The plog-converter runs automatically with the Txt output type on Windows, and errorfile on other platforms, and whatever's inside that file gets sent to stderr. Then the PVS log file gets deleted after the converter does its thing — no leftovers, we love a clean queen. 🧹✨

This property is initialized by the value of the CMAKE_<LANG>_PVS_STUDIO variable if it's set when a target is created.

📏 `<LANG>_STANDARD`

Okay so the variations are giving a whole family reunion:

C_STANDARD
CXX_STANDARD
CUDA_STANDARD
HIP_STANDARD
OBJC_STANDARD
OBJCXX_STANDARD

These properties say which language standard versions you're requesting. And here's the tea: if you ask for a newer standard than the compiler can actually support, it will fallback to the latest supported standard. This "decay" behavior can be controlled with the <LANG>_STANDARD_REQUIRED target property. 🍂

Heads up bestie: the actual language standard used may be higher than what <LANG>_STANDARD says, and that's true regardless of <LANG>_STANDARD_REQUIRED's value. Specifically, usage requirements or the use of compile features can raise the required language standard above what <LANG>_STANDARD specifies. Surprise upgrade, no cap. ⬆️

These properties are initialized by the value of the CMAKE_<LANG>_STANDARD variable if it's set when the target is created.

For the supported values and CMake versions, go check the respective pages. And to control compiler-specific extensions, see <LANG>_EXTENSIONS.

See the cmake-compile-features(7) manual for the info on compile features and a list of supported compilers. 📚

🔒 `<LANG>_STANDARD_REQUIRED`

The variations, again, a whole squad:

C_STANDARD_REQUIRED
CXX_STANDARD_REQUIRED
CUDA_STANDARD_REQUIRED
HIP_STANDARD_REQUIRED
OBJC_STANDARD_REQUIRED
OBJCXX_STANDARD_REQUIRED

These ones specify whether the value of <LANG>_STANDARD is an actual requirement. When it's false or unset, the <LANG>_STANDARD target property is treated as optional and is allowed to "decay" to a previous standard if the standard you requested isn't available. Chill vibes. 😌 When <LANG>_STANDARD_REQUIRED is set to true, then <LANG>_STANDARD becomes a hard requirement and a fatal error gets issued if that requirement can't be met. No compromises, no mercy. 💀

Same note as before, and it still matters: the actual language standard used may be higher than what <LANG>_STANDARD specifies, regardless of the value of <LANG>_STANDARD_REQUIRED. Usage requirements or the use of compile features can raise the required language standard above what <LANG>_STANDARD specifies. yes, again. it's important. 🫶

These properties are initialized by the value of the CMAKE_<LANG>_STANDARD_REQUIRED variable if it's set when a target is created.

See the cmake-compile-features(7) manual for information on compile features and a list of supported compilers.

🫥 `<LANG>_VISIBILITY_PRESET`

The one-liner energy: value for symbol visibility compile flags.

This property decides the value passed in a visibility related compile option, like -fvisibility= for <LANG>. It affects compilation in sources of all types of targets — every single one, no exceptions. See policy CMP0063. 📜

This property is initialized by the value of the CMAKE_<LANG>_VISIBILITY_PRESET variable if it's set when a target is created.

📦 `LIBRARY_OUTPUT_DIRECTORY`

Output directory where LIBRARY target files get built. 🗂️

This property specifies the directory into which library target files should be built. The property value may use generator expressions. And here's the plot twist: multi-configuration generators (Visual Studio, Xcode, Ninja Multi-Config) append a per-configuration subdirectory onto the directory you specified — unless a generator expression is used, in which case they mind their business. ✨

This property is initialized by the value of the CMAKE_LIBRARY_OUTPUT_DIRECTORY variable if it's set when a target is created.

See also the LIBRARY_OUTPUT_DIRECTORY_<CONFIG> target property.

📦 `LIBRARY_OUTPUT_DIRECTORY_<CONFIG>`

Per-configuration output directory for LIBRARY target files. It's the LIBRARY_OUTPUT_DIRECTORY we just talked about, but config-specific. 🎀

But NOT in a copy-paste way, because here's the difference: multi-configuration generators (Visual Studio Generators, Xcode) do NOT append a per-configuration subdirectory to the specified directory here. None of that. It is what it is. 💅

This property is initialized by the value of the CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG> variable if it's set when a target is created.

Contents of LIBRARY_OUTPUT_DIRECTORY_<CONFIG> may use generator expressions.

🏷️ `LIBRARY_OUTPUT_NAME`

Output name for LIBRARY target files — specifically the base name for library target files. It overrides the OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties, so it's like the main character stepping in front of the supporting cast. 👑

See also the LIBRARY_OUTPUT_NAME_<CONFIG> target property.

🏷️ `LIBRARY_OUTPUT_NAME_<CONFIG>`

Per-configuration output name for LIBRARY target files — this is just the configuration-specific version of the LIBRARY_OUTPUT_NAME target property. Same energy, one config at a time. 🌈

🔗 `LINK_DEPENDS`

Additional files on which a target binary depends for linking. 🧷

It specifies a semicolon-separated list of full-paths to files that the link rule for this target depends on. The target binary gets linked if any of the named files is newer than it. Basically: "if this file changed, re-link me."

Only the Ninja and Makefile Generators support this property. It's intended for specifying dependencies on "linker scripts" for custom Makefile link rules. ikykyk 🫶

Contents of LINK_DEPENDS may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for the available expressions, and the cmake-buildsystem(7) manual for more on defining buildsystem properties.

🚫 `LINK_DEPENDS_NO_SHARED`

Do not depend on linked shared library files. Bold. Iconic. 🙅‍♀️

Set this property to true and you're telling CMake generators not to add file-level dependencies on the shared library files that this target links. The consequence? Modifications to those shared libraries won't be enough to re-link this target. It just won't care. 😤

Logical target-level dependencies are NOT affected though, so the linked shared libraries will still be brought up to date before this target is built. The order stays correct, bestie. 🫡

This property is initialized by the value of the CMAKE_LINK_DEPENDS_NO_SHARED variable if it's set when a target is created.

🧭 `LINK_DIRECTORIES`

Added in version 3.13.

List of directories to use for the link step of shared library, module and executable targets. 🎯

This property holds a semicolon-separated list of directories specified so far for its target. Use the target_link_directories() command to append more search directories — it's the glow-up button. ✨

This property is initialized by the LINK_DIRECTORIES directory property when a target is created, and it's used by the generators to set the search directories for the linker.

Contents of LINK_DIRECTORIES may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions, and the cmake-buildsystem(7) manual for more on defining buildsystem properties. 💜

💅 LINK_FLAGS

Extra flags you want on the link step, bestie — that's it, that's the property. Applies when the target is a shared library, a module library, or an executable. Static libraries? They don't get to play here — they gotta use STATIC_LIBRARY_OPTIONS or STATIC_LIBRARY_FLAGS instead. ✨

So LINK_FLAGS itself is managed as a string, and you use it to tack extra flags onto a target's link step. Then LINK_FLAGS_<CONFIG> adds to a specific configuration <CONFIG> — like DEBUG, RELEASE, MINSIZEREL, RELWITHDEBINFO, … you get the vibe. 🎀

Heads up queen: this property has been superseded by the LINK_OPTIONS property. Like, it still works, but it's giving legacy energy.

🦋 LINK_FLAGS_<CONFIG>

Per-configuration linker flags for a SHARED library, MODULE, or EXECUTABLE target.

It's literally just the configuration-specific version of LINK_FLAGS. Same vibes, one config at a time.

Same warning, bestie: this has been superseded by the LINK_OPTIONS property too. 😭

🌸 LINK_INTERFACE_LIBRARIES

The list of public interface libraries for a shared library or executable. Lowkey the "who do I bring with me" list.

So here's the default tea: when you link to a shared library target, you transitively link to whatever that library itself was linked with. But for an executable with exports — peep the ENABLE_EXPORTS target property — no default transitive link dependencies get used at all. This property is the override: it replaces those default transitive link dependencies with an explicit list you hand-pick. 💖

When the target gets linked into another target via the target_link_libraries() command, the libraries you list (and recursively their link interface libraries) get provided to that other target too. And if the list is empty? Then no transitive link dependencies get incorporated when this target is linked into another target — even if the default set was non-empty. Iconic boundary-setting, honestly. 🫶

This property gets initialized from the value of the CMAKE_LINK_INTERFACE_LIBRARIES variable if that's set when the target is created. And it's straight-up ignored for STATIC libraries.

Also: this property is overridden by the INTERFACE_LINK_LIBRARIES property if policy CMP0022 is NEW.

🚨 And the big one: this property is deprecated. Use INTERFACE_LINK_LIBRARIES instead. Like, for real for real.

Creating Relocatable Packages

Okay so do not populate the LINK_INTERFACE_LIBRARIES of a target with absolute paths to dependencies. That would hard-code into your installed packages the library file paths for dependencies exactly as found on the machine the package was made on — and that machine is not everyone's machine, bestie. It's giving "works on my computer" energy. 💀

For the full discussion of the extra care you gotta take when specifying usage requirements while creating packages for redistribution, go read the Creating Relocatable Packages section of the cmake-packages(7) manual.

🎀 LINK_INTERFACE_LIBRARIES_<CONFIG>

Per-configuration list of public interface libraries for a target. 🌈

This is the configuration-specific version of LINK_INTERFACE_LIBRARIES. And if you set it, it completely overrides the generic property for that named configuration. No blending, no merging — full takeover.

This property is overridden by the INTERFACE_LINK_LIBRARIES property if policy CMP0022 is NEW.

🚨 Deprecated again, bestie. Use INTERFACE_LINK_LIBRARIES instead.

Creating Relocatable Packages

Same rule, different property: don't populate LINK_INTERFACE_LIBRARIES_<CONFIG> of a target with absolute paths to dependencies. That hard-codes into installed packages the library file paths for dependencies as found on the machine the package was made on. 🙈

See the Creating Relocatable Packages section of the cmake-packages(7) manual for the discussion of additional care that must be taken when specifying usage requirements while creating packages for redistribution.

🔥 LINK_INTERFACE_MULTIPLICITY

Repetition count for STATIC libraries with cyclic dependencies. Yes, cyclic. Like your group chat. 🔁

When you link to a STATIC library target with cyclic dependencies, the linker may need to scan through the archives more than once — specifically inside the strongly connected component of the dependency graph. CMake by default builds the link line so the linker scans through that component at least twice. This property sets the minimum number of scans, if it's larger than the default. And CMake uses the largest value specified by any target in a component. Biggest number wins, periodt. 👑

⭐ LINK_INTERFACE_MULTIPLICITY_<CONFIG>

Per-configuration repetition count for cycles of STATIC libraries.

This is the configuration-specific version of LINK_INTERFACE_MULTIPLICITY. If set, it completely overrides the generic property for the named configuration. Same energy as before — full override, no crumbs. 🍓

💜 LINK_LIBRARIES

The list of direct link dependencies. The main character of link properties, honestly.

This property specifies the list of libraries or targets that'll be used for linking. And it doesn't only take values from the target_link_libraries() command — you can set values directly on any target with the set_property() command too. Flexible icon. ✨

The generators use the value of this property to construct the link rule for the target. Here's the order, bestie: the direct link dependencies get linked first, followed by indirect dependencies from the transitive closure of the direct dependencies' INTERFACE_LINK_LIBRARIES properties. See policy CMP0022.

Contents of LINK_LIBRARIES may use generator expressions with the $<...> syntax. And policy CMP0131 affects how the LINK_ONLY generator expression behaves for this property.

For more on defining buildsystem properties, see the cmake-buildsystem(7) manual.

📌 Note: a call to target_link_libraries(<target> ...) may update this property on <target>. And if <target> wasn't created in the same directory as the call, then target_link_libraries() will wrap each entry in the form ::@(directory-id);...;::@, where the ::@ is literal and the (directory-id) is unspecified. This tells the generators that the named libraries must be looked up in the scope of the caller, not the scope where <target> was created. Valid directory ids get stripped on export by the install(EXPORT) and export() commands. No cap.

In advanced use cases, usage requirements from dependencies may update the list of direct link dependencies specified by this property. Peep the INTERFACE_LINK_LIBRARIES_DIRECT and INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE target properties.

And for how CMake orders direct link dependencies on linker command lines, see the CMAKE_LINK_LIBRARIES_STRATEGY variable and the corresponding LINK_LIBRARIES_STRATEGY target property. 🧚

Handling Compiler Driver Differences

Added in version 4.0.

Every compiler driver has its own little syntax for passing options to the linker tool. Rude, but true. The LINKER: prefix and the , separator let you specify, in a portable way, options to pass to the linker tool. LINKER: gets replaced by the appropriate driver option, and , gets replaced by the appropriate driver separator. Those two are given by the values of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.

Example time, because this is so much clearer with one:

For "LINKER:-z,defs" you get:

-Xlinker -z -Xlinker defs for Clang
-Wl,-z,defs for GNU GCC

And the LINKER: prefix also supports an alternative syntax — specify arguments with the SHELL: prefix and a space as the separator. So that previous example becomes "LINKER:SHELL:-z defs". Slay. 💅

⚠️ Note: specifying the SHELL: prefix anywhere other than at the beginning of the LINKER: prefix is not supported. Front of the line or nowhere, bestie.

🌟 LINK_LIBRARIES_ONLY_TARGETS

Added in version 3.23.

Enforces that link items which could be target names are actually existing targets. Basically a vibe check on your link items. 👀

Set this property to a true value to turn on extra checks on the contents of the LINK_LIBRARIES and INTERFACE_LINK_LIBRARIES target properties — typically populated by target_link_libraries(). The checks also apply to libraries added to a target through the INTERFACE_LINK_LIBRARIES_DIRECT properties of its dependencies. CMake will verify that link items that might be target names actually name existing targets.

An item counts as a possible target name if:

it does not contain a / or \, and
it does not start in -, and
(for historical reasons) it does not start in $ or `.

This property is initialized by the value of the CMAKE_LINK_LIBRARIES_ONLY_TARGETS variable when a non-imported target is created. And you can explicitly enable it on an imported target to check its link interface.

So like, in this example CMake will halt with an error at configure time because miLib is not a target (it's a typo, bestie, we've all been there 😭):

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

Now, if you want to link toolchain-provided libraries by name while still enforcing LINK_LIBRARIES_ONLY_TARGETS, use an imported Interface Library with the IMPORTED_LIBNAME target property:

add_library(toolchain::m INTERFACE IMPORTED)
set_property(TARGET toolchain::m PROPERTY IMPORTED_LIBNAME "m")
target_link_libraries(myExe PRIVATE toolchain::m)

Also peep policy CMP0028. 🦋

📌 Note: if INTERFACE_LINK_LIBRARIES contains generator expressions, its actual list of link items may depend on the type and properties of the consuming target. In those cases CMake may not always catch names of missing targets that only show up for specific consumers. And a future version of CMake with improved heuristics may start throwing errors on projects that previous versions of CMake happily accepted. Just so you're not blindsided. 💀

🍓 LINK_LIBRARIES_STRATEGY

Added in version 3.31.

Okay so bestie, this property is literally the vibe-check for how your target's direct link dependencies get ordered on the linker command line 🎀 It gets its starting value from the CMAKE_LINK_LIBRARIES_STRATEGY variable if it's set at the moment the target is created.

CMake builds a target's link line out of its Target Link Properties. Like, specifically, the LINK_LIBRARIES target property holds that target's direct link dependencies — usually you populated it by calling target_link_libraries(). Then the indirect link dependencies get propagated from those entries of LINK_LIBRARIES that name library targets, by chasing down the transitive closure of their INTERFACE_LINK_LIBRARIES properties. CMake ships with multiple strategies for the nominal ordering of direct + indirect link deps, and those get filtered afterwards for Toolchain-Specific Behavior.

Peep this example so the strategies below make sense 👇

add_library(A STATIC ...)
add_library(B STATIC ...)
add_library(C STATIC ...)
add_executable(main ...)
target_link_libraries(B PRIVATE A)
target_link_libraries(C PRIVATE A)
target_link_libraries(main PRIVATE A B C)

Here are the supported strategies:

REORDER_MINIMALLY — Entries of LINK_LIBRARIES always show up first and in their original order, no cap. Indirect link dependencies that aren't already satisfied by the original entries may get reordered and de-duplicated among themselves, but they're always appended after the original entries. Yeah, this can give you a less efficient link line, but it hands projects the keys to ordering among independent entries 🔑 That control matters when you're intermixing link flags with libraries, or when multiple libraries provide the same symbol. This one is the default, bestie. In the example above, this strategy computes a link line for main by starting with its original entries A B C, then appending another A to satisfy the deps of B and C on A. Nominal order: A B C A.

Heads up: extra filtering for Toolchain-Specific Behavior might de-duplicate that A on the actual linker invocation in the generated build system, so you'd end up with either A B C or B C A.

REORDER_FREELY — Entries of LINK_LIBRARIES may be reordered, de-duplicated, and intermixed with indirect link dependencies 💅 Slightly more efficient link lines, but projects get zero say in ordering among independent entries. In the example above, this strategy computes a link line for main by re-ordering its original entries A B C so the deps of B and C on A are satisfied. Nominal order: B C A.

🧚 Toolchain-Specific Behavior

After one of those strategies produces a nominal order among direct and indirect link deps, the actual linker invocation in the generated build system may still de-duplicate entries based on platform-specific requirements and what the linker can actually do. See policy CMP0156.

For example, if REORDER_MINIMALLY produces A B C A, the real link line might de-dupe that A like so:

If A is a static library and the linker re-scans automatically, the first occurrence is kept → A B C. See policy CMP0179.
If A is a shared library on Windows, the first occurrence is kept → A B C.
If A is a shared library on macOS or UNIX platforms, the last occurrence is kept → B C A.

`LINK_LIBRARY_OVERRIDE`

Added in version 3.24.

This one overrides the library features tied to libraries coming out of LINK_LIBRARY generator expressions 🦋 It's your fix-it button for incompatible library features — the kind of mess you get when you specify different features for the same library in different LINK_LIBRARY generator expressions.

It can override multiple libraries and multiple features at once. It expects a semicolon-separated list, where each list item looks like this:

feature[,link-item]*

So for every comma-separated link-item, any library feature already chilling on it gets ignored — for the target this property is set on — and the item gets associated with the specified feature instead ✨ Each link-item can be anything that would be accepted as part of a library-list in a LINK_LIBRARY generator expression.

add_library(lib1 ...)
add_library(lib2 ...)
add_library(lib3 ...)

target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>")
target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>")
target_link_libraries(lib3 PRIVATE lib1 lib2)

# lib1 is associated with both feature2 and no feature. Without any override,
# this would result in a fatal error at generation time for lib3.
# Define an override to resolve the incompatible feature associations.
set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE "feature2,lib1,external")

# lib1 and external will now be associated with feature2 instead when linking lib3

You can also override anything with the pre-defined DEFAULT library feature 🙈 That basically discards whatever feature that link item had, for that target only — lib3 in this example:

# When linking lib3, discard any library feature for lib1, and use feature2 for external
set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE
  "DEFAULT,lib1"
  "feature2,external"
)

That example also shows you how to set different feature overrides for different link items 💜 Also check out the LINK_LIBRARY_OVERRIDE_<LIBRARY> target property — it's an alternative way to override library features for individual libraries and is lowkey simpler in some cases. If both properties are defined and both specify an override for the same link item, LINK_LIBRARY_OVERRIDE_<LIBRARY> takes precedence over LINK_LIBRARY_OVERRIDE.

Contents of LINK_LIBRARY_OVERRIDE may use generator expressions.

Wanna know more about library features? See the CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE> and CMAKE_LINK_LIBRARY_USING_<FEATURE> variables 🫶

`LINK_LIBRARY_OVERRIDE_<LIBRARY>`

Added in version 3.24.

Overrides the library feature associated with <LIBRARY> from LINK_LIBRARY generator expressions 🌸 Same energy as above: it resolves incompatible library features that come from specifying different features for <LIBRARY> across different LINK_LIBRARY generator expressions.

When you set this on a target, the property holds a single library feature name, and that's what gets applied to <LIBRARY> when linking that target:

add_library(lib1 ...)
add_library(lib2 ...)
add_library(lib3 ...)

target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>")
target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>")
target_link_libraries(lib3 PRIVATE lib1 lib2)

# lib1 is associated with both feature2 and no feature. Without any override,
# this would result in a fatal error at generation time for lib3.
# Define an override to resolve the incompatible feature associations.
set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 feature2)

# lib1 will now be associated with feature2 instead when linking lib3

And yeah, you can override any feature with the pre-defined DEFAULT library feature, which effectively discards any feature for that link item, for that target only (lib3 here) 💅

# When linking lib3, discard any library feature for lib1
set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 DEFAULT)

See the LINK_LIBRARY_OVERRIDE target property for the alternative way of overriding library features for multiple libraries all at once. If both properties are defined and specify an override for the same link item, LINK_LIBRARY_OVERRIDE_<LIBRARY> wins over LINK_LIBRARY_OVERRIDE 👑

Contents of LINK_LIBRARY_OVERRIDE_<LIBRARY> may use generator expressions.

For the deets on library features, see the CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE> and CMAKE_LINK_LIBRARY_USING_<FEATURE> variables 🍓

`LINK_OPTIONS`

Added in version 3.13.

List of options to use for the link step of shared library, module and executable targets, plus the device link step 🔥 Targets that are static libraries need to use the STATIC_LIBRARY_OPTIONS target property instead, okay?

These options get used for both normal linking and device linking (see policy CMP0105). If you wanna control link options for normal vs. device link steps separately, use the $<HOST_LINK> and $<DEVICE_LINK> generator expressions ✨

This property holds a semicolon-separated list of options specified so far for its target. Use the target_link_options() command to append more options.

It's initialized by the LINK_OPTIONS directory property when a target is created, and the generators use it to set the options for the compiler.

Contents of LINK_OPTIONS may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for the available expressions, and the cmake-buildsystem(7) manual for more on defining buildsystem properties 💖

Note: bestie, use this property in preference to the LINK_FLAGS property. Like, for real fr fr.

✨ Host And Device Specific Link Options ✨

Added in version 3.18 🎀 Okay so bestie, when a device link step is involved — and that's controlled by the CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS properties plus policy CMP0105 — the raw options get delivered to both the host and device link steps (wrapped in -Xcompiler or the equivalent for device link, iykyk).

Options wrapped with the $<DEVICE_LINK:...> generator expression get used only for the device link step 💅
Options wrapped with the $<HOST_LINK:...> generator expression get used only for the host link step 🫶

🌈 Option De-duplication 🌈

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. Then that set gets de-duplicated so you don't get the same option screaming at you seventeen times. Periodt.

Added in version 3.12: the way that de-dup is great for individual options but it will absolutely break up option groups, no cap. For example, -option A -option B becomes -option A B. 😭 So if you need to keep a group together, specify a group of options using shell-like quoting along with a SHELL: prefix. The SHELL: prefix gets dropped, and the rest of the option string is parsed using separate_arguments() in UNIX_COMMAND mode. So like:

"SHELL:-option A" "SHELL:-option B"

becomes -option A -option B and the group stays cute and intact 💖

🦋 Handling Compiler Driver Differences 🦋

Every compiler driver has its own lil syntax for handing options to the linker tool, and honestly? Iconic of them. Anyway — the LINKER: prefix and , separator let you specify, in a portable way, options to pass to the linker tool. LINKER: gets replaced by the appropriate driver option and , by the appropriate driver separator. Those two are given by the values of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables 🌸

So for example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for Clang and -Wl,-z,defs for GNU GCC. Slay 💅

The LINKER: prefix can be specified as part of a SHELL: prefix expression too.

And LINKER: supports an alternative syntax — you can specify arguments using the SHELL: prefix and space as the separator. That previous example then becomes "LINKER:SHELL:-z defs" ✨

Note: specifying the SHELL: prefix anywhere other than at the beginning of the LINKER: prefix is not supported. Don't do it, bestie, it's not the vibe 🙈

💀 `LINK_SEARCH_END_STATIC` 💀

End a link line such that static system libraries are used.

Some linkers support switches like -Bstatic and -Bdynamic to decide whether to use static or shared libraries for -lXXX options. CMake uses these options to set the link type for libraries whose full paths aren't known, or (in some cases) which 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 that final linker search type to -Bstatic regardless of how it started 🔥

This property is initialized by the value of the variable CMAKE_LINK_SEARCH_END_STATIC if it's set when a target is created.

See also LINK_SEARCH_START_STATIC 👑

⭐ `LINK_SEARCH_START_STATIC` ⭐

Assume the linker looks for static libraries by default.

Same deal as above — some linkers support switches like -Bstatic and -Bdynamic to determine whether to use static or shared libraries for -lXXX options, and CMake uses these to set the link type for libraries whose full paths aren't known or (in some cases) are in implicit link directories for the platform. By default the linker search type is assumed to be -Bdynamic at the beginning of the library list. This property switches the assumption to -Bstatic. It's intended for use when linking an executable statically (e.g. with the GNU -static option) 🧚

This property is initialized by the value of the variable CMAKE_LINK_SEARCH_START_STATIC if it's set when a target is created.

🔥 `LINK_WARNING_AS_ERROR` 🔥

Added in version 4.0.

Specify whether to treat warnings on link as errors. If enabled, it adds a flag to treat warnings on link as errors. But — if the cmake --link-no-warning-as-error option is given on the cmake(1) command line, this property is ignored. Rules are rules 😌

This property takes a semicolon-separated list of the following values:

LINKER: treat the linker warnings as errors.
DRIVER: treat the compiler warnings as errors when used to drive the link step. See the COMPILE_WARNING_AS_ERROR target property for more information.

Moreover, for consistency with the COMPILE_WARNING_AS_ERROR target property, a boolean value can be specified too:

True value: this is equivalent to LINKER and DRIVER values.
False value: deactivate this feature for the target.

Lowkey important: this property is not implemented for all linkers. It's silently ignored if there's no implementation for the linker being used. The currently implemented compiler linker IDs are:

AIX
AppleClang
GNU
GNUgold
LLD
MOLD
MSVC
Solaris
WILD

This property is initialized by the value of the variable CMAKE_LINK_WARNING_AS_ERROR if it's set when a target is created.

🎀 `LINK_WHAT_YOU_USE` 🎀

Added in version 3.7.

This is a boolean option that, when set to TRUE, adds a link-time check that prints a list of shared libraries being linked but providing no symbols used by the target. It's intended as a lint, bestie — a lil vibe check on your link line 🦋

The flag specified by CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG gets passed to the linker so that all libraries specified on the command line get linked into the target. Then the command specified by CMAKE_LINK_WHAT_YOU_USE_CHECK runs after the target is linked, to check the binary for unnecessarily-linked shared libraries. So thorough 💅

Note: for now, it's only supported for ELF platforms and only applies to executable and shared or module library targets. This property will be ignored for any other targets and configurations. Not me being picky, that's just how it is 😭

This property is initialized by the value of the CMAKE_LINK_WHAT_YOU_USE variable if it's set when a target is created.

🌸 `LINKER_LANGUAGE` 🌸

Specifies the language whose compiler will invoke the linker.

For executables, shared libraries, and modules, this sets the language whose compiler is used to link the target (like "C" or "CXX"). A typical value for an executable is the language of the source file providing the program entry point (main). If it's not set, the language with the highest linker preference value is the default. Details of the linker preferences are considered internal, but there's some limited discussion under the internal CMAKE_<LANG>_LINKER_PREFERENCE variables, iykyk 🤫

If this property isn't set by the user, it will be calculated at generate-time by CMake. Main character energy, honestly — it just figures itself out 👑

🌈 `LINKER_TYPE` 🌈

Added in version 3.29.

Specify which linker will be used for the link step. The property value may use generator expressions ✨

Note: it's assumed that the linker you specify is fully compatible with the default one the compiler would normally invoke. CMake will not do any option translation. No translating, no fixing, no rescuing you 🫶

Linker types are case-sensitive and may only contain letters, numbers and underscores. Linker types defined in all uppercase are reserved for CMake's own built-in types. The pre-defined linker types are:

DEFAULT — this type corresponds to standard linking, essentially equivalent to the LINKER_TYPE target property not being set at all.
SYSTEM — use the standard linker provided by the platform or toolchain. For example, this implies the Microsoft linker for all MSVC-compatible compilers. Supported for the following platform-compiler combinations:
- Linux: GNU, Clang, LLVMFlang, NVIDIA, and Swift compilers.
- Apple platforms: AppleClang, Clang, GNU, and Swift compilers.
- Windows: MSVC, GNU, Clang, NVIDIA, and Swift compilers.
LLD — use the LLVM linker. Supported for the following platform-compiler combinations:
- Linux: GNU, Clang, LLVMFlang, NVIDIA, and Swift compilers.
- Apple platforms: Clang, AppleClang, and Swift compilers.
- Windows: GNU, Clang with MSVC-like front-end, Clang with GNU-like front-end, MSVC, NVIDIA with MSVC-like front-end, and Swift.
BFD — use the GNU linker. Supported for the following platform-compiler combinations:
- Linux: GNU, Clang, LLVMFlang, and NVIDIA compilers.
- Windows: GNU, Clang with GNU-like front-end.
GOLD — supported on Linux platform with GNU, Clang, LLVMFlang, NVIDIA, and Swift compilers.
MOLD — use the mold linker (https://github.com/rui314/mold). Supported on the following platform-compiler combinations:
- Linux: GNU, Clang, LLVMFlang, and NVIDIA compilers.
- Apple platforms: Clang and AppleClang compilers (acts as an alias to the sold linker, https://github.com/bluewhalesystems/sold).
SOLD — use the sold linker (https://github.com/bluewhalesystems/sold). Only supported on Apple platforms with Clang and AppleClang compilers.
WILD — Added in version 4.4. Use the wild linker (https://github.com/wild-linker/wild). Only supported on Linux platforms with Clang and GNU compilers. 🔥
APPLE_CLASSIC — use the Apple linker in the classic behavior (i.e. before Xcode 15.0). Only supported on Apple platforms with GNU, Clang, AppleClang, and Swift compilers.
MSVC — use the Microsoft linker. Only supported on the Windows platform with MSVC, Clang with MSVC-like front-end, and Swift compilers.

This property is not supported on the Green Hills MULTI generator 💀

So basically the toolchain's gonna hear about the implementation details through the CMAKE_<LANG>_USING_LINKER_<TYPE> variable — that's the one that carries the actual flags and command-line options for us. Like, watch:

add_library(lib1 SHARED ...)
set_property(TARGET lib1 PROPERTY LINKER_TYPE LLD)

That's telling CMake "bestie, lib1 links with linker type LLD, no arguments." And then the command line options that get passed to the toolchain? Those come from CMAKE_<LANG>_USING_LINKER_LLD. Slay.

💡 Quick note tho: you'd typically set the linker once for the whole build with CMAKE_LINKER_TYPE instead of going target-by-target with LINKER_TYPE. Like, do less, achieve more. 👑

💅 LOCATION

Read-only location of a target on disk. That's it, that's the property — it's giving "where does this thing actually live."

If it's an imported target, this read-only property hands you the value of the LOCATION_<CONFIG> property for an unspecified <CONFIG> that the target provides.

If it's a non-imported target, this property exists purely for compat with CMake 2.4 and below. Back in the day it was meant to grab an executable target's output file location so you could use it in add_custom_command(). And the path might contain a build-system-specific chunk that gets swapped out at build time for whatever config is actually being built (think $(ConfigurationName) in VS). But CMake 2.6 and up? add_custom_command() just recognizes a target name in its COMMAND and DEPENDS options and computes the location itself. And in CMake 2.8.4 and above, add_custom_command() understands generator expressions to refer to target locations anywhere in the command. So yeah — this property is genuinely not needed for making custom commands anymore. ✨

⚠️ Do NOT set properties that affect a target's location after reading this property. We're talking about names matching (RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?, (IMPLIB_)?(PREFIX|SUFFIX), or "LINKER_LANGUAGE". If you break this rule, CMake does not diagnose it — it just leaves the target's location undefined. Not cute. Not it. 💀

🎀 LOCATION_<CONFIG>

Read-only property giving you a target location on disk, per-config.

It tells you where a target's main file sits on disk for the configuration <CONFIG>. Heads up: it's only defined for library and executable targets. And an imported target may hand you a whole different set of configurations than whatever the importing project uses. By default CMake goes for an exact match, otherwise it just picks an arbitrary available configuration. Want control? Use the MAP_IMPORTED_CONFIG_<CONFIG> property to map imported configurations explicitly. 🌸

⚠️ Same rule, same energy: don't set location-affecting properties after reading this one. That includes names matching (RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?, (IMPLIB_)?(PREFIX|SUFFIX), or LINKER_LANGUAGE. Break it and nothing gets diagnosed — the target location is just left undefined. 🙈

🧚 MACHO_COMPATIBILITY_VERSION

Added in version 3.17.

What compatibility version number is this target for Mach-O binaries.

For shared libraries on Mach-O systems (macOS, iOS, that whole squad) the MACHO_COMPATIBILITY_VERSION property is the compatibility version, and MACHO_CURRENT_VERSION is the current version. Both of these get embedded right into the shared library binary, and you can peek at them with the otool -L <binary> command. Obsessed with a little introspection moment.

Okay but like — important: MACHO_CURRENT_VERSION and MACHO_COMPATIBILITY_VERSION do not touch the file names or the version-related symlinks CMake generates for the library. The VERSION and SOVERSION target properties still own file and symlink naming. And the install_name is still controlled by SOVERSION. Periodt.

When MACHO_CURRENT_VERSION and MACHO_COMPATIBILITY_VERSION aren't given, VERSION and SOVERSION are used for the version details embedded in the binaries, respectively. So you only need to set the MACHO ones if your project actually needs to decouple file/symlink naming from the version details baked into the binaries — e.g. to match libtool conventions. 🦋

⭐ MACHO_CURRENT_VERSION

Added in version 3.17.

What current version number is this target for Mach-O binaries.

Same deal, flipped: for shared libraries on Mach-O systems (macOS, iOS) MACHO_COMPATIBILITY_VERSION is the compatibility version and MACHO_CURRENT_VERSION is the current version. Both embedded in the shared library binary, both checkable with otool -L <binary>. 🔥

And again — MACHO_CURRENT_VERSION and MACHO_COMPATIBILITY_VERSION do not affect file names or version-related symlinks. VERSION and SOVERSION still control those. install_name still controlled by SOVERSION.

When they're not given, VERSION and SOVERSION fill in for the embedded version details respectively. Only set the MACHO pair when you need to decouple the naming from the embedded versions, like for libtool conventions. 💜

🌈 MACOSX_BUNDLE

Build an executable as an Application Bundle on macOS or iOS.

Set this to TRUE and your executable, when built on macOS or iOS, becomes an application bundle — a full GUI executable you can launch right from the Finder. Main character energy fr. For the deets on how the Info.plist file for the bundle gets created, check the MACOSX_BUNDLE_INFO_PLIST target property. And this property gets initialized from the value of the CMAKE_MACOSX_BUNDLE variable if that's set when the target is created. 🫶

🍓 MACOSX_BUNDLE_INFO_PLIST

Specify a custom Info.plist template for a macOS and iOS Application Bundle.

If an executable target has MACOSX_BUNDLE enabled, it builds as an application bundle on macOS. By default its Info.plist gets created by configuring a template called MacOSXBundleInfo.plist.in that lives in CMAKE_MODULE_PATH. This property lets you point at an alternative template file name — full paths are fine, go off. ✨

And these target properties can be set to specify what content gets configured into the file:

MACOSX_BUNDLE_BUNDLE_NAME — Sets CFBundleName.
MACOSX_BUNDLE_BUNDLE_VERSION — Sets CFBundleVersion.
MACOSX_BUNDLE_COPYRIGHT — Sets NSHumanReadableCopyright.
MACOSX_BUNDLE_GUI_IDENTIFIER — Sets CFBundleIdentifier.
MACOSX_BUNDLE_ICON_FILE — Sets CFBundleIconFile.
MACOSX_BUNDLE_INFO_STRING — Sets CFBundleGetInfoString.
MACOSX_BUNDLE_LONG_VERSION_STRING — Sets CFBundleLongVersionString.
MACOSX_BUNDLE_SHORT_VERSION_STRING — Sets CFBundleShortVersionString.

CMake variables with the same names can also be set, and they affect every target in a directory that doesn't have the specific property set. And if you specify a custom Info.plist via this property, you can of course just hard-code all the settings in there instead of using the target properties. Your call bestie. 🎀

💖 MACOSX_FRAMEWORK_INFO_PLIST

Specify a custom Info.plist template for a macOS and iOS Framework.

A library target with FRAMEWORK enabled builds as a framework on macOS. By default its Info.plist gets created by configuring a template called MacOSXFrameworkInfo.plist.in located in CMAKE_MODULE_PATH. This property names an alternative template file — full path totally allowed. 🌟

These target properties can be set to specify content configured into the file:

MACOSX_FRAMEWORK_BUNDLE_NAME — Added in version 3.31. Sets CFBundleName.
MACOSX_FRAMEWORK_BUNDLE_VERSION — Sets CFBundleVersion.
MACOSX_FRAMEWORK_ICON_FILE — Sets CFBundleIconFile.
MACOSX_FRAMEWORK_IDENTIFIER — Sets CFBundleIdentifier.
MACOSX_FRAMEWORK_SHORT_VERSION_STRING — Sets CFBundleShortVersionString.

Same story as the bundle one: CMake variables of the same name affect all targets in a directory that don't have each specific property set, and a custom Info.plist can just hard-code everything instead. 🦋

💀 MACOSX_RPATH

Whether this target on macOS or iOS is located at runtime using rpaths.

Set it to TRUE and the directory portion of this shared library's install_name field becomes @rpath — unless INSTALL_NAME_DIR overrides it. Which is basically saying "this shared library gets found at runtime via runtime paths (rpaths)." Iconic.

This property is initialized by the value of the CMAKE_MACOSX_RPATH variable if it's set when the target is created.

Runtime paths also get embedded in binaries that use this target, and you can control those with the INSTALL_RPATH target property on whatever target is linking to this one. 🔗

Policy CMP0042 was introduced to flip the default value of MACOSX_RPATH to TRUE. Why? Because @rpath is just a more flexible and powerful alternative to @executable_path and @loader_path. Newer, better, ate. 💅

🌸 MANUALLY_ADDED_DEPENDENCIES

Added in version 3.8.

Get manually added dependencies to other top-level targets.

This read-only property lets you query all the dependencies that were added for this target via the add_dependencies() command. Handy if you wanna know what you hand-wired in. 🫶

👑 MAP_IMPORTED_CONFIG_<CONFIG>

Map from project configuration to imported target's configuration.

lowkey the most important part of this property: it does nothing for non-imported targets. Like sorry bestie, it's imported-only. 🙈

If you set this property and no matching configurations are available, then the imported target is considered to be not found. That's it, that's the vibe check. 💀

This property gets initialized by the value of the CMAKE_MAP_IMPORTED_CONFIG_<CONFIG> variable if it's set when the target is created. Slay, defaults. ✨

Example 🎀

So like, picture this: you're creating an imported C++ library called foo:

add_library(foo STATIC IMPORTED)

Use the foo_debug path for the Debug build type:

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}"
  )

Use the foo_release path for the Release build type:

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}"
  )

And now use the Release version of the library for the MinSizeRel and RelWithDebInfo build types:

set_target_properties(foo PROPERTIES
  MAP_IMPORTED_CONFIG_MINSIZEREL Release
  MAP_IMPORTED_CONFIG_RELWITHDEBINFO Release
  )

See how that works? The map is mapping your configs onto configs that actually exist. Iconic behavior fr fr. 🫶

MSVC_DEBUG_INFORMATION_FORMAT 💅

Added in version 3.25.

Okay so this one picks the debug information format when you're targeting the MSVC ABI. Very demure, very mind-your-business, until you need debug info. 🐛

The allowed values are:

Embedded — compile with -Z7 or equivalent flag(s) to produce object files with full symbolic debugging information.
ProgramDatabase — compile with -Zi or equivalent flag(s) to produce a program database that contains all the symbolic debugging information.
EditAndContinue — compile with -ZI or equivalent flag(s) to produce a program database that supports the Edit and Continue feature.

The value is ignored on compilers not targeting the MSVC ABI, but an unsupported value will be rejected as an error when using a compiler targeting the MSVC ABI. So don't get cute with it. 😭

The value may also be the empty string (""), in which case no debug information format flag will be added explicitly by CMake. Silent. Mysterious. ✨

Use generator expressions to support per-configuration specification. For example, the code:

add_executable(foo foo.c)
set_property(TARGET foo PROPERTY
  MSVC_DEBUG_INFORMATION_FORMAT "$<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>")

...selects for the target foo the program database debug information format for the Debug and RelWithDebInfo configurations. Ate. 🔥

This property is initialized from the value of the CMAKE_MSVC_DEBUG_INFORMATION_FORMAT variable, if it is set. If this property is not set, CMake selects a debug information format using the default value $<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>, if supported by the compiler, and otherwise $<$<CONFIG:Debug,RelWithDebInfo>:Embedded>.

Note: this property has effect only when policy CMP0141 is set to NEW prior to the first project() or enable_language() command that enables a language using a compiler targeting the MSVC ABI. Read that twice, bestie. Policy first, property second, no exceptions. 💀

MSVC_RUNTIME_CHECKS 🧚

Added in version 4.0.

Brand new, fresh out the box — selects the list of enabled runtime checks when targeting the MSVC ABI.

The allowed values are:

PossibleDataLoss — compile with -RTCc or equivalent flag(s) to enable possible data loss checks.
StackFrameErrorCheck — compile with -RTCs or equivalent flag(s) to enable stack frame error checks.
UninitializedVariable — compile with -RTCu or equivalent flag(s) to enable uninitialized variables checks.

The value is ignored on compilers not targeting the MSVC ABI, but an unsupported value will be rejected as an error when using a compiler targeting the MSVC ABI. Same energy as above. 🙈

The value may also be the empty string (""), in which case no runtime error check flags will be added explicitly by CMake.

Use generator expressions to support per-configuration specification. For example, the code:

add_executable(foo foo.c)
set_property(TARGET foo PROPERTY
  MSVC_RUNTIME_CHECKS "$<$<CONFIG:Debug,RelWithDebInfo>:PossibleDataLoss;UninitializedVariable>")

...enables for the target foo the possible data loss and uninitialized variables checks for the Debug and RelWithDebInfo configurations. Look at that semicolon doing the lord's work. 😌

This property is initialized from the value of the CMAKE_MSVC_RUNTIME_CHECKS variable, if it is set. If this property is not set, CMake selects runtime checks using the default value $<$<CONFIG:Debug>:StackFrameErrorCheck;UninitializedVariable>, if supported by the compiler, or an empty value otherwise.

Note: this property has effect only when policy CMP0184 is set to NEW prior to the first project() or enable_language() command that enables a language using a compiler targeting the MSVC ABI. (Yes, different policy number than the last one. Don't mix them up. 😭)

MSVC_RUNTIME_LIBRARY 🌸

Added in version 3.15.

Selects the MSVC runtime library for use by compilers targeting the MSVC ABI. This is the one everybody asks about in the group chat, ngl.

The allowed values are:

"" (set but empty) — 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. So like, you said nothing, but VS said something anyway. Rude. 💀

MultiThreaded — compile with -MT or equivalent flag(s) to use a multi-threaded statically-linked runtime library.
MultiThreadedDLL — compile with -MD or equivalent flag(s) to use a multi-threaded dynamically-linked runtime library.
MultiThreadedDebug — compile with -MTd or equivalent flag(s) to use a multi-threaded statically-linked runtime library.
MultiThreadedDebugDLL — compile with -MDd or equivalent flag(s) to use a multi-threaded dynamically-linked runtime library.

The value is ignored on compilers not targeting the MSVC ABI, but an unsupported value will be rejected as an error when using a compiler targeting the MSVC ABI. Periodt. ✨

Use generator expressions to support per-configuration specification. For example, the code:

add_executable(foo foo.c)
set_property(TARGET foo PROPERTY
  MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")

...selects for the target foo a multi-threaded statically-linked runtime library with or without debug information depending on the configuration. Chef's kiss generator-expression moment. 👑

The property is initialized from the value of the CMAKE_MSVC_RUNTIME_LIBRARY variable, if it is set. If the property is not set, then CMake uses the default value MultiThreaded$<$<CONFIG:Debug>:Debug>DLL to select a MSVC runtime library.

Note: this property has effect only when policy CMP0091 is set to NEW prior to the first project() or enable_language() command that enables a language using a compiler targeting the MSVC ABI. Three properties, three different policies. CMake really said "collect them all." 🫠

NAME ⭐

Logical name for the target.

Read-only logical name for the target as used by CMake. You can look, but you cannot touch. 💅

NO_SONAME 🎀

Whether to set soname when linking a shared library.

Enable this boolean property if a generated SHARED library should not have soname set. Default is to set soname 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. 🫣

So like... read that warning again before you flip this boolean. It's giving "works on my machine" and then never works anywhere else. 😭

NO_SYSTEM_FROM_IMPORTED 🦋

Do not treat include directories from the interfaces of consumed Imported Targets as system directories.

Okay let me actually break this down because it's a whole paragraph and it matters:

When the consumed target's SYSTEM property is set to true, the contents of the INTERFACE_INCLUDE_DIRECTORIES target property are treated as system includes or, on Apple platforms, when the target is a framework, it will be treated as system. By default, SYSTEM is true for imported targets and false for other target types.

If the NO_SYSTEM_FROM_IMPORTED property is set to true on a consuming target, compilation of sources in that consuming target will not treat the contents of the INTERFACE_INCLUDE_DIRECTORIES of consumed imported targets as system includes, even if that imported target's SYSTEM property is false.

Directories listed in the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES property of consumed targets are not affected by NO_SYSTEM_FROM_IMPORTED. Those directories will always be treated as system include directories by consumers. Always. No notes. 👑

This property is initialized by the value of the CMAKE_NO_SYSTEM_FROM_IMPORTED variable if it is set when a target is created.

See the EXPORT_NO_SYSTEM target property to set this behavior on the target providing the include directories rather than the target consuming them. Provider vs. consumer, the eternal struggle. 🌈

OBJC_EXTENSIONS 🍓

Added in version 3.16.

Boolean specifying whether compiler specific extensions are requested.

This property specifies whether compiler specific extensions should be used. For some compilers, this results in adding a flag such as -std=gnu11 instead of -std=c11 to the compile line. This property is ON by default. The basic OBJC standard level is controlled by the OBJC_STANDARD target property.

So yeah, gnu over here being the main character by default. Very on brand. ✨

if that property is still not set and the project already set C_EXTENSIONS, then C_EXTENSIONS’s value gets copied over to OBJC_EXTENSIONS. slay. ✨

See the cmake-compile-features(7) manual for the deets on compile features and the list of supported compilers.

This property is initialized by the value of the CMAKE_OBJC_EXTENSIONS variable if it’s set when a target is created, and otherwise by the value of CMAKE_OBJC_EXTENSIONS_DEFAULT (see CMP0128). 🫶

🍓 `OBJC_STANDARD` 🍓

Added in version 3.16.

The OBJC standard whose features are requested to build this target.

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 -std=gnu11 to the compile line.

Supported values are:

90 — Objective C89/C90
99 — Objective C99
11 — Objective C11
17 — Added in version 3.21. Objective C17
23 — Added in version 3.21. Objective C23

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:

set_property(TARGET tgt PROPERTY OBJC_STANDARD 11)

with a compiler which does not support -std=gnu11 or an equivalent flag will not result in an error or warning, but will instead add the -std=gnu99 or -std=gnu90 flag if supported. This “decay” behavior may be controlled with the OBJC_STANDARD_REQUIRED target property. Additionally, the OBJC_EXTENSIONS target property may be used to control whether compiler-specific extensions are enabled on a per-target basis.

If the property is not set, and the project has set the C_STANDARD, the value of C_STANDARD is set for OBJC_STANDARD.

See the cmake-compile-features(7) manual for information on compile features and a list of supported compilers.

This property is initialized by the value of the CMAKE_OBJC_STANDARD variable if it is set when a target is created. 💅

🌸 `OBJC_STANDARD_REQUIRED` 🌸

Added in version 3.16.

Boolean describing whether the value of OBJC_STANDARD is a requirement.

If this property is set to ON, then the value of the OBJC_STANDARD target property is treated as a requirement. If this property is OFF or unset, the OBJC_STANDARD target property is treated as optional and may “decay” to a previous standard if the requested is not available.

If the property is not set, and the project has set the C_STANDARD_REQUIRED, the value of C_STANDARD_REQUIRED is set for OBJC_STANDARD_REQUIRED.

See the cmake-compile-features(7) manual for information on compile features and a list of supported compilers.

This property is initialized by the value of the CMAKE_OBJC_STANDARD_REQUIRED variable if it is set when a target is created. 🎀

🦋 `OBJCXX_EXTENSIONS` 🦋

Added in version 3.16.

Boolean specifying whether compiler specific extensions are requested.

This property specifies whether compiler specific extensions should be used. For some compilers, this results in adding a flag such as -std=gnu++11 instead of -std=c++11 to the compile line. This property is ON by default. The basic ObjC++ standard level is controlled by the OBJCXX_STANDARD target property.

See the cmake-compile-features(7) manual for information on compile features and a list of supported compilers.

If the property is not set, and the project has set the CXX_EXTENSIONS, the value of CXX_EXTENSIONS is set for OBJCXX_EXTENSIONS.

This property is initialized by the value of the CMAKE_OBJCXX_EXTENSIONS variable if set when a target is created and otherwise by the value of CMAKE_OBJCXX_EXTENSIONS_DEFAULT (see CMP0128). 😭

💜 `OBJCXX_STANDARD` 💜

Added in version 3.16.

The ObjC++ standard whose features are requested to build this target.

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 -std=gnu++11 to the compile line.

Supported values are:

98 — Objective C++98
11 — Objective C++11
14 — Objective C++14
17 — Objective C++17
20 — Objective C++20
23 — Added in version 3.20. Objective C++23
26 — Added in version 3.25. Objective C++26. CMake 3.25 and later recognize 26 as a valid value, no version has support for any compiler.

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:

set_property(TARGET tgt PROPERTY OBJCXX_STANDARD 11)

with a compiler which does not support -std=gnu++11 or an equivalent flag will not result in an error or warning, but will instead add the -std=gnu++98 flag if supported. This “decay” behavior may be controlled with the OBJCXX_STANDARD_REQUIRED target property. Additionally, the OBJCXX_EXTENSIONS target property may be used to control whether compiler-specific extensions are enabled on a per-target basis.

If the property is not set, and the project has set the CXX_STANDARD, the value of CXX_STANDARD is set for OBJCXX_STANDARD.

See the cmake-compile-features(7) manual for information on compile features and a list of supported compilers.

This property is initialized by the value of the CMAKE_OBJCXX_STANDARD variable if it is set when a target is created. ✨

🌈 `OBJCXX_STANDARD_REQUIRED` 🌈

Added in version 3.16.

Boolean describing whether the value of OBJCXX_STANDARD is a requirement.

If this property is set to ON, then the value of the OBJCXX_STANDARD target property is treated as a requirement. If this property is OFF or unset, the OBJCXX_STANDARD target property is treated as optional and may “decay” to a previous standard if the requested is not available.

If the property is not set, and the project has set the CXX_STANDARD_REQUIRED, the value of CXX_STANDARD_REQUIRED is set for OBJCXX_STANDARD_REQUIRED.

See the cmake-compile-features(7) manual for information on compile features and a list of supported compilers.

This property is initialized by the value of the CMAKE_OBJCXX_STANDARD_REQUIRED variable if it is set when a target is created. 🫶

🔥 `OPTIMIZE_DEPENDENCIES` 🔥

Added in version 3.19.

Activates dependency optimization of static and object libraries.

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’t actually link against anything.

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:

The dependency was added to the library by add_dependencies().
The dependency was added to the library through a source file in the library generated by a custom command that uses the dependency.
The dependency has any PRE_BUILD, PRE_LINK, or POST_BUILD custom commands associated with it.
The dependency contains any source files that were generated by a custom command. However, if CMP0154 is NEW for the dependency and it uses File Sets, only source files that are scoped as PUBLIC, INTERFACE, or of type CXX_MODULES are considered.
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).

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.

This property is initialized by the value of the CMAKE_OPTIMIZE_DEPENDENCIES variable when the target is created. 💀

🎀 `OSX_ARCHITECTURES` 🎀

Target specific architectures for macOS.

The OSX_ARCHITECTURES property sets the target binary architecture for targets on macOS (-arch). This property is initialized by the value of the variable CMAKE_OSX_ARCHITECTURES if it is set when a target is created. Use OSX_ARCHITECTURES_<CONFIG> to set the binary architectures on a per-configuration basis, where <CONFIG> is an upper-case name (e.g. OSX_ARCHITECTURES_DEBUG). 🍓

🌟 `OSX_ARCHITECTURES_<CONFIG>` 🌟

Per-configuration macOS and iOS binary architectures for a target.

This property is the configuration-specific version of OSX_ARCHITECTURES. 💖

👑 `OUTPUT_NAME` 👑

Output name for target files. that’s the whole vibe. 🎀

So this one sets the base name for output files that get created for an executable or library target. If you don't set it, the logical target name is what's used by default during generation — but heads up bestie, the value is not set by default during configuration. ✨

Contents of OUTPUT_NAME and all the variants listed below may use generator expressions. 👑

See also the variants, because there are so many of them:

OUTPUT_NAME_<CONFIG>
ARCHIVE_OUTPUT_NAME_<CONFIG>
ARCHIVE_OUTPUT_NAME
LIBRARY_OUTPUT_NAME_<CONFIG>
LIBRARY_OUTPUT_NAME
RUNTIME_OUTPUT_NAME_<CONFIG>
RUNTIME_OUTPUT_NAME

🎀 `OUTPUT_NAME_<CONFIG>` 🎀

Per-configuration target file base name. Basically it's the configuration-specific version of the OUTPUT_NAME target property — same vibe, just one config at a time. 💅

🌸 `PCH_INSTANTIATE_TEMPLATES` 🌸

Added in version 3.19.

When you set this property to true, the precompiled header compiler options will contain a flag that instantiates templates during the generation of the PCH — if it's supported, obvi. This can significantly improve your compile times, which is honestly iconic. 🔥 Supported in Clang since version 11.

This property is initialized by the value of the CMAKE_PCH_INSTANTIATE_TEMPLATES variable if it is set when a target is created. If that variable is not set, the property defaults to ON.

🦋 `PCH_WARN_INVALID` 🦋

Added in version 3.18.

When this property is set to true, the precompile header compiler options will contain a compiler flag that should warn you about invalid precompiled headers — like -Winvalid-pch for the GNU compiler. Ngl that warning will save your whole afternoon. 😭

This property is initialized by the value of the CMAKE_PCH_WARN_INVALID variable if it is set when a target is created. If that variable is not set, the property defaults to ON.

💜 `PDB_NAME` 💜

The output name for the MS debug symbol .pdb file that the linker generates for an executable or shared library target.

This property specifies the base name for the debug symbols file. If you don't set it, the OUTPUT_NAME target property value or the logical target name gets used by default.

Added in version 4.1: Contents of PDB_NAME may use generator expressions. ✨

Note, bestie: this property does not apply to STATIC library targets, because no linker is invoked to produce them, so they have no linker-generated .pdb file containing debug symbols. 🫶 The linker-generated program database files are specified by the /pdb linker flag and are not the same as compiler-generated program database files specified by the /Fd compiler flag. Use the COMPILE_PDB_NAME property to specify the latter.

🍓 `PDB_NAME_<CONFIG>` 🍓

Per-configuration output name for the MS debug symbol .pdb file generated by the linker for an executable or shared library target.

This is just the configuration-specific version of PDB_NAME.

Added in version 4.1: Contents of PDB_NAME_<CONFIG> may use generator expressions. 💖

Note: this property does not apply to STATIC library targets because no linker is invoked to produce them, so they have no linker-generated .pdb file containing debug symbols. The linker-generated program database files are specified by the /pdb linker flag and are not the same as compiler-generated program database files specified by the /Fd compiler flag. Use the COMPILE_PDB_NAME_<CONFIG> property to specify the latter.

🌈 `PDB_OUTPUT_DIRECTORY` 🌈

Output directory for the MS debug symbols .pdb file generated by the linker for an executable or shared library target.

This property specifies the directory into which the MS debug symbols will be placed by the linker. 📁

Added in version 3.12: The property value may use generator expressions. Multi-configuration generators append a per-configuration subdirectory to the specified directory unless a generator expression is used. Sneaky but fair. 😌

This property is initialized by the value of the CMAKE_PDB_OUTPUT_DIRECTORY variable if it is set when a target is created.

Note: this property does not apply to STATIC library targets because no linker is invoked to produce them, so they have no linker-generated .pdb file containing debug symbols. The linker-generated program database files are specified by the /pdb linker flag and are not the same as compiler-generated program database files specified by the /Fd compiler flag. Use the COMPILE_PDB_OUTPUT_DIRECTORY property to specify the latter.

⭐ `PDB_OUTPUT_DIRECTORY_<CONFIG>` ⭐

Per-configuration output directory for the MS debug symbol .pdb file generated by the linker for an executable or shared library target.

This is a per-configuration version of PDB_OUTPUT_DIRECTORY, but multi-configuration generators (Visual Studio Generators, Xcode) do NOT append a per-configuration subdirectory to the specified directory. Periodt. 💅

This property is initialized by the value of the CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG> variable if it is set when a target is created.

Added in version 3.12: Contents of PDB_OUTPUT_DIRECTORY_<CONFIG> may use generator expressions. 🦋

Note: this property does not apply to STATIC library targets because no linker is invoked to produce them, so they have no linker-generated .pdb file containing debug symbols. The linker-generated program database files are specified by the /pdb linker flag and are not the same as compiler-generated program database files specified by the /Fd compiler flag. Use the COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> property to specify the latter.

👑 `POSITION_INDEPENDENT_CODE` 👑

A target property that specifies whether to create a target that has position-independent code enabled. It's lowkey the main character of linker-adjacent properties. 🫶

The POSITION_INDEPENDENT_CODE target property determines whether position-independent executables or libraries will be created. This property is True by default for SHARED and MODULE library targets. For other targets, this property is initialized by the value of the CMAKE_POSITION_INDEPENDENT_CODE variable if it is set when the target is created, or False otherwise.

Note: for executable targets, the link step is controlled by the CMP0083 policy and the CheckPIESupported module. Don't forget them, bestie. 💀

Position-independent code (PIC) refers to machine code that executes properly regardless of its absolute memory address. This is particularly important for shared libraries, which are often loaded at different memory addresses by different programs. Generating position-independent code ensures that these libraries can be safely and efficiently shared among multiple processes without causing address conflicts. On some platforms (notably UNIX-like systems), generating PIC is also a requirement for creating shared libraries. 🧚

Use of position-independent code is recommended or required in the following cases:

When building shared or module libraries (e.g., with add_library(... SHARED), or add_library(... MODULE)), where PIC allows dynamic relocation at runtime.
When building executables as position-independent executables (PIE), which can enhance security by enabling Address Space Layout Randomization (ASLR).
On platforms or toolchains that require PIC for certain types of linking or sandboxed environments.

Enabling PIC can result in slightly larger or slower code on some architectures, but this is often outweighed by the benefits of flexibility and security. Small price, big slay. 💖

✨ Examples ✨

Enabling PIC for a static library target:

add_library(foo STATIC foo.c)
set_target_properties(foo PROPERTIES POSITION_INDEPENDENT_CODE TRUE)

Enabling PIC for an executable target:

add_executable(app app.c)

set_target_properties(app PROPERTIES POSITION_INDEPENDENT_CODE TRUE)

# Additionally, pass PIE-related link-time options to executable(s).
include(CheckPIESupported)
check_pie_supported()

🌸 See Also 🌸

The CheckPIESupported module to pass PIE-related options to the linker for executables.

🎀 `PRECOMPILE_HEADERS` 🎀

Added in version 3.16.

List of header files to precompile. 🧠✨

This property holds a semicolon-separated list of header files to precompile specified so far for its target. Use the target_precompile_headers() command to append more header files.

This property supports generator expressions. 💅

🦋 `PRECOMPILE_HEADERS_REUSE_FROM` 🦋

Added in version 3.16.

Target from which to reuse the precompiled headers build artifact. Recycling! ♻️

See the second signature of the target_precompile_headers() command for more detailed information.

💜 `PREFIX` 💜

What comes before the library name. Yeah, that's literally it. 😌

A target property that can be set to override the prefix (such as lib) on a library name.

🍓 `PRIVATE_HEADER` 🍓

Specify private header files in a FRAMEWORK shared library target. 🍎

Shared library targets marked with the FRAMEWORK 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 PRIVATE_HEADER option to the install(TARGETS) command.

🌈 `PRIVATE_HEADER_SETS_TO_VERIFY` 🌈

Added in version 4.3.

Used to specify which PUBLIC and PRIVATE header sets of a target should be verified as private headers. Vibe check for your headers, fr fr. 🔍

This property contains a semicolon-separated list of header sets which should be verified if VERIFY_PRIVATE_HEADER_SETS is set to true. If the list is empty, all PUBLIC and PRIVATE header sets are verified. If the project does not want to verify any private header sets on the target, set VERIFY_PRIVATE_HEADER_SETS to false.

See also INTERFACE_HEADER_SETS_TO_VERIFY. 🫶

PROJECT_LABEL

Changes the name of a target in an IDE ✨ — like, the label you see instead of the raw target name.

Can be used to change the name of the target in an IDE like Visual Studio. Cute, right?

PUBLIC_HEADER

Specifies the public header files in a FRAMEWORK shared library target 🎀.

Shared library targets marked with the FRAMEWORK 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 Headers directory inside the framework folder. On non-Apple platforms these headers may be installed using the PUBLIC_HEADER option to the install(TARGETS) command.

RESOURCE

Specifies resource files in a FRAMEWORK or BUNDLE 💅.

Target marked with the FRAMEWORK or BUNDLE 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. Resources directory for macOS) inside the bundle. On non-Apple platforms these files may be installed using the RESOURCE option to the install(TARGETS) command.

Following example of Application Bundle:

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}")

will produce flat structure for iOS systems:

ExecutableTarget.app
  appres.txt
  ExecutableTarget
  Info.plist
  resourcefile.txt

For macOS systems it will produce following directory structure:

ExecutableTarget.app/
  Contents
    Info.plist
    MacOS
      ExecutableTarget
    Resources
      appres.txt
      resourcefile.txt

For Linux, such CMake script produce following files:

ExecutableTarget
Resources
  appres.txt
  resourcefile.txt

RULE_LAUNCH_COMPILE

Specifies a launcher for compile rules 🚀.

Note: this property is intended for internal use by ctest(1). Projects and developers should use the <LANG>_COMPILER_LAUNCHER target properties or the associated CMAKE_<LANG>_COMPILER_LAUNCHER variables instead. Like, fr fr, that's the way.

See the global property RULE_LAUNCH_COMPILE of the same name for details. This overrides the global and directory property for a target.

RULE_LAUNCH_CUSTOM

Specifies a launcher for custom rules.

See the global property of the same name for details. This overrides the global and directory property for a target.

RULE_LAUNCH_LINK

Specifies a launcher for link rules.

Note: this property is intended for internal use by ctest(1). Projects and developers should use the <LANG>_LINKER_LAUNCHER target properties or the associated CMAKE_<LANG>_LINKER_LAUNCHER variables instead.

See the global property RULE_LAUNCH_LINK of the same name for details. This overrides the global and directory property for a target.

RUNTIME_OUTPUT_DIRECTORY

The output directory in which to build RUNTIME target files 🗂️.

This property specifies the directory into which runtime target files should be built. The property value may use generator expressions. Multi-configuration generators (Visual Studio, Xcode, Ninja Multi-Config) append a per-configuration subdirectory to the specified directory unless a generator expression is used.

This property is initialized by the value of the CMAKE_RUNTIME_OUTPUT_DIRECTORY variable if it is set when a target is created.

See also the RUNTIME_OUTPUT_DIRECTORY_<CONFIG> target property.

RUNTIME_OUTPUT_DIRECTORY_<CONFIG>

Per-configuration output directory for RUNTIME target files ✨.

This is a per-configuration version of the RUNTIME_OUTPUT_DIRECTORY target property, but multi-configuration generators (Visual Studio Generators, Xcode) do NOT append a per-configuration subdirectory to the specified directory — not me confirming that twice, it's just that important 💀. This property is initialized by the value of the CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG> variable if it is set when a target is created.

Contents of RUNTIME_OUTPUT_DIRECTORY_<CONFIG> may use generator expressions.

RUNTIME_OUTPUT_NAME

The output name for RUNTIME target files.

This property specifies the base name for runtime target files. It overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties.

See also the RUNTIME_OUTPUT_NAME_<CONFIG> target property.

RUNTIME_OUTPUT_NAME_<CONFIG>

Per-configuration output name for RUNTIME target files.

This is the configuration-specific version of the RUNTIME_OUTPUT_NAME target property.

Rust_EDITION

Added in version 4.4.

Note: Experimental. Gated by CMAKE_EXPERIMENTAL_RUST.

The Rust edition required to build this target 👑. It is initialized from the CMAKE_Rust_EDITION variable if defined. Setting this property results in adding a flag such as --edition=2018 to the compile line.

Supported values are:

2015 — Rust 2015, the default edition, started with Rust 1.0.
2018 — Rust 2018, available since Rust 1.31.
2021 — Rust 2021, available since Rust 1.56.
2024 — Rust 2024, available since Rust 1.85.

SKIP_BUILD_RPATH

Should rpaths be used for the build tree? 🤔

SKIP_BUILD_RPATH is a boolean specifying whether to skip automatic generation of an rpath allowing the target to run from the build tree, see also the BUILD_RPATH target property. This property is initialized by the value of the variable CMAKE_SKIP_BUILD_RPATH if it is set when a target is created.

SKIP_LINTING

Added in version 4.2.

Excludes all sources of a target from running configured linting tools 🧹✨.

When this boolean property is enabled on a target, C/C++ linting tools enabled for that target (e.g. <LANG>_CPPLINT, <LANG>_CLANG_TIDY, <LANG>_CPPCHECK, <LANG>_ICSTAT and <LANG>_INCLUDE_WHAT_YOU_USE) will not be invoked for source files compiled by the target. If the SKIP_LINTING source-file property is set on a specific source or if the SKIP_LINTING file set property is set, it takes precedence over this target-wide property.

This is a convenience alternative to setting the SKIP_LINTING source file property individually on each source. If either the target's SKIP_LINTING or file set's SKIP_LINTING including this source or a source's SKIP_LINTING is enabled, that source will be excluded from linting.

The property has no effect on targets that do not have sources.

SOURCE_DIR

Added in version 3.4.

This read-only property reports the value of the CMAKE_CURRENT_SOURCE_DIR variable in the directory in which the target was defined 📍.

SOURCE_DIRS

Added in version 4.4.

Semicolon-separated list of base directories of the target's default source set (i.e. the file set with name and type SOURCES). The property supports generator expressions 🦋.

This property is normally only set by target_sources(FILE_SET) rather than being manipulated directly.

See SOURCE_DIRS_<NAME> for the list of base directories in other source sets.

SOURCE_DIRS_<NAME>

Added in version 4.4.

Semicolon-separated list of base directories of the target's <NAME> source set, which has the set type SOURCES. The property supports generator expressions.

This property is normally only set by target_sources(FILE_SET) rather than being manipulated directly.

See SOURCE_DIRS for the list of base directories in the default source set. See SOURCE_SETS for the file set names of all source sets.

SOURCE_SET

Added in version 4.4.

Semicolon-separated list of files in the target's default source set, (i.e. the file set with name and type SOURCES). If any of the paths are relative, they are computed relative to the target's source directory. The property supports generator expressions 🌈.

This property is normally only set by target_sources(FILE_SET) rather than being manipulated directly.

See SOURCE_SET_<NAME> for the list of files in other source sets.

SOURCE_SET_<NAME>

Added in version 4.4.

Semicolon-separated list of files in the target's <NAME> source set, which has the set type SOURCES. If any of the paths are relative, they are computed relative to the target's source directory. The property supports generator expressions 🎀.

This property is normally only set by target_sources(FILE_SET) rather than being manipulated directly.

See SOURCE_SET for the list of files in the default source set. See SOURCE_SETS for the file set names of all source sets.

SOURCE_SETS

Added in version 4.4.

Read-only list of the target's PRIVATE and PUBLIC source sets (i.e. all file sets with the type SOURCES). Files listed in these file sets are treated as source files 💖.

Source sets can be defined with the target_sources() command's FILE_SET option, using type SOURCES 💅

Also go peek at SOURCE_SET_<NAME>, SOURCE_SET and INTERFACE_SOURCE_SETS — they're the besties of this property, fr fr.

✨ SOURCES ✨

This one specifies the list of paths to source files for the target 📂 The following commands all set or add to the SOURCES target property, and they're the normal way to mess with it:

add_executable()
add_library()
add_custom_target()
target_sources()

Contents of SOURCES may use generator expressions 🌈 If a path starts with a generator expression, it's expected to evaluate to an absolute path. Not doing that? That's undefined behavior, bestie — don't 💀

Paths that are for files generated by the build get treated as relative to the build directory of the target, if the path isn't already specified as an absolute path. Heads up though: whether a file counts as generated may be affected by the CMP0118 and CMP0163 policies 👀

If a path does not start with a generator expression, is not an absolute path, and is not a generated file, it gets treated as relative to the location picked by the first of these that matches:

If a file by the specified path exists relative to the target's source directory, use that file 💖
If policy CMP0115 is not set to NEW, try appending each known source file extension to the path and check if that exists relative to the target's source directory 🎀
Repeat the above two steps, this time relative to the target's binary directory instead 🌸

Ngl, all those decisions above are made at generation time, not build time. Periodt.

See the cmake-buildsystem(7) manual for more on defining buildsystem properties ✨

💜 SOVERSION 💜

The ABI version number of a shared library target, iykyk.

For shared libraries, VERSION and SOVERSION can be used to specify the build version and ABI 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 one is assumed to have the same version number. SOVERSION is ignored if the NO_SONAME property is set 💀

A common convention is to specify both VERSION and SOVERSION such that SOVERSION matches the first component of VERSION:

set_target_properties(mylib PROPERTIES VERSION 1.2.3 SOVERSION 1)

The idea being: breaking changes to the ABI increment both the SOVERSION and the major VERSION number 🔥

🌈 Windows Versions 🌈

For shared libraries and executables on Windows, the VERSION attribute is parsed to extract a <major>.<minor> version number. Those numbers get used as the image version of the binary 🪟

🦋 Mach-O Versions 🦋

For shared libraries and executables on Mach-O systems (e.g. macOS, iOS), the SOVERSION property corresponds to the compatibility version and VERSION corresponds to the current version (unless Mach-O specific overrides are provided, as discussed below). See the FRAMEWORK target property for an example 🍎

For shared libraries, the MACHO_COMPATIBILITY_VERSION and MACHO_CURRENT_VERSION properties can be used to override the compatibility version and current version respectively. Note that SOVERSION will still be used to form the install_name, and both SOVERSION and VERSION may also affect the file and symlink names 👑

Versions of Mach-O binaries may be checked with the otool -L <binary> command 🔍

🌸 SPDX_LICENSE 🌸

Added in version 4.1.

Specify the license(s) of a target using a System Package Data Exchange (SPDX) License Expression 💖 That's the SPDX spec at https://spdx.github.io/spdx-spec/v3.0.1/annexes/spdx-license-expressions/, and the project itself lives at https://spdx.dev/. See the SPDX License List at https://spdx.org/licenses/ for a list of commonly used licenses and their identifiers 🎀

⭐ STATIC_LIBRARY_FLAGS ⭐

Archiver (or MSVC librarian) flags for a static library target 📚 Targets that are shared libraries, modules, or executables need to use the LINK_OPTIONS or LINK_FLAGS target properties instead — wrong tool, bestie 🙈

The STATIC_LIBRARY_FLAGS property, managed as a string, can be used to add extra flags to the link step of a static library target. STATIC_LIBRARY_FLAGS_<CONFIG> will add to the configuration <CONFIG>, for example, DEBUG, RELEASE, MINSIZEREL, RELWITHDEBINFO, ...

Note: This property has been superseded by the STATIC_LIBRARY_OPTIONS property. It's giving deprecated energy 💀

💫 `STATIC_LIBRARY_FLAGS_<CONFIG>` 💫

Per-configuration archiver (or MSVC librarian) flags for a static library target.

This is the configuration-specific version of STATIC_LIBRARY_FLAGS 🌟

Note: This property has been superseded by the STATIC_LIBRARY_OPTIONS property. Same vibe, same warning 🫶

👑 STATIC_LIBRARY_OPTIONS 👑

Added in version 3.13.

Archiver (or MSVC librarian) flags for a static library target. Targets that are shared libraries, modules, or executables need to use the LINK_OPTIONS target property instead 🌈

This property holds a semicolon-separated list of options specified so far for its target. Use set_target_properties() or set_property() commands to set its content ✨

Contents of STATIC_LIBRARY_OPTIONS may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions. See the cmake-buildsystem(7) manual for more on defining buildsystem properties 💖

Note: This property must be used in preference to the STATIC_LIBRARY_FLAGS property. Like, actually. Please 👏

🧚 Option De-duplication 🧚

Added in version 3.12: While beneficial for individual options, the de-duplication step can break up option groups. For example, -option A -option B becomes -option A B 😭

One may specify a group of options using shell-like quoting along with a SHELL: prefix. The SHELL: prefix is dropped, and the rest of the option string is parsed using the separate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A" "SHELL:-option B" becomes -option A -option B 🎀

🔥 Handling Archiver Driver Differences 🔥

Added in version 4.0.

To pass options to the archiver tool, each compiler driver has its own syntax. The ARCHIVER: prefix and , separator can be used to specify, in a portable way, options to pass to the archiver tool. ARCHIVER: is replaced by the appropriate driver option and , by the appropriate driver separator. The driver prefix and driver separator are given by the values of the CMAKE_<LANG>_ARCHIVER_WRAPPER_FLAG and CMAKE_<LANG>_ARCHIVER_WRAPPER_FLAG_SEP variables 🌟

The ARCHIVER: prefix can be specified as part of a SHELL: prefix expression 👀

The ARCHIVER: prefix supports, as an alternative syntax, specification of arguments using the SHELL: prefix and space as separator.

Note: Specifying the SHELL: prefix anywhere other than at the beginning of the ARCHIVER: prefix is not supported. Don't test it, bestie 💀

🎀 SUFFIX 🎀

What comes after the target name, literally.

A target property that can be set to override the suffix (such as .so or .exe) on the name of a library, module or executable 🦋

💜 Swift_COMPILATION_MODE 💜

Added in version 3.29.

Specify how Swift compiles a target 🐦 The allowed values are:

incremental — Compiles each Swift source in the module separately, resulting in better parallelism in the build. The compiler emits additional information into the build directory improving rebuild performance when small changes are made to the source between rebuilds. This is the best option to use while iterating on changes in a project ✨
wholemodule — Whole-module optimizations are slowest to compile, but results in the most optimized library. The entire context is loaded into once instance of the compiler, so there is no parallelism across source files in the module 👑
singlefile — Compiles each source in a Swift modules separately, resulting in better parallelism. Unlike the incremental build mode, no additional information is emitted by the compiler during the build, so rebuilding after making small changes to the source file will not run faster. This option should be used sparingly, preferring incremental builds, unless working around a compiler bug 🙈

Use generator expressions to support per-configuration specification. For example, the code:

add_library(foo foo.swift)
set_property(TARGET foo PROPERTY
  Swift_COMPILATION_MODE "$<IF:$<CONFIG:Release>,wholemodule,incremental>")

sets the Swift compilation mode to wholemodule mode in the release configuration and sets the property to incremental mode in other configurations 🌈

The property is initialized from the value of the CMAKE_Swift_COMPILATION_MODE variable, if it is set. If the property is not set or is empty, then CMake uses the default value incremental to specify the swift compilation mode 💖

Note: This property only has effect when policy CMP0157 is set to NEW prior to the first project() or enable_language() command that enables the Swift language. Read that again, bestie — prior to 😭

🌟 Swift_DEPENDENCIES_FILE 🌟

Added in version 3.15.

This property sets the path for the Swift dependency file (swiftdep) for the target. If one is not specified, it will default to <TARGET>.swiftdeps 🎀

🦋 Swift_ LANGUAGE_VERSION 🦋

Added in version 3.16.

(Yeah, that's the whole beginning of it — hold that thought, it keeps going in the next bit 🫶)

This property sets the language version for the Swift sources in the target. If you don't pick one, it defaults to <code>CMAKE_Swift_LANGUAGE_VERSION</code> if that's specified — and if that's not a thing either, it just chills at the latest version the compiler supports. 💅

`Swift_MODULE_DIRECTORY`

Added in version 3.15.

Okay so this one ✨specifies the output directory for Swift modules provided by the target✨.

If the target actually contains Swift source files, this is the dir where the modules get placed. When this property isn't set, the modules land in the build directory corresponding to the target's source directory. And!! if the variable CMAKE_Swift_MODULE_DIRECTORY is set when a target is created, its value is used to initialize this property. 🎀

Added in version 4.0: the property value may use generator expressions. Multi-configuration generators (Ninja Multi-Config) append a per-configuration subdirectory to the specified directory unless a generator expression is used. iykyk 🦋

Warning: the Xcode generator straight-up ignores this property. 🙈 not her fault, she's just built different.

`Swift_MODULE_NAME`

Added in version 3.15.

This property specifies the name of the Swift module, bestie. It defaults to the name of the target — but with hyphens replaced by underscores, because hyphens are not valid in Swift module identifiers. grammar icon behavior 💀

`Swift_PACKAGE_NAME`

Added in version 4.4.

Specify the Swift package name for a target 🫶

This property sets the package name passed to the Swift compiler via the -package-name flag, which is what enables package access control in Swift code.

Note: package access control was added in Swift 5.8 and Xcode 15. So this target property has no effect when you're using an earlier version of Swift or Xcode. she simply won't show up 💅

If the property is not set, the PROJECT_NAME variable is used as the default package name. See policy CMP0216.

And ngl setting this property to the empty string will result in the target being compiled without a package name. clean slate energy ✨

`Swift_SEPARATE_MODULE_EMISSION`

Added in version 4.4.

Emit Swift modules separately from compilation in the Ninja Generators. 👑

When this property is set to ON on an importable Swift target built by Ninja Generators, CMake emits a separate -emit-module build edge that produces the .swiftmodule independently of object compilation. The way this slays is that downstream Swift targets can start compiling as soon as the module interface is available, instead of waiting around for all the upstream compilation outputs. main character move fr fr 🔥

The property is initialized from the value of the CMAKE_Swift_SEPARATE_MODULE_EMISSION variable, if it's set. If this property is not set, separate module emission is enabled by default. See policy CMP0215.

Note: separate module emission takes effect only when policy CMP0157 is set to NEW prior to the first project() or enable_language() command that enables the Swift language. timing is everything bestie ⏰

`SYMBOLIC`

Added in version 4.2.

Read-only indication of whether a target is SYMBOLIC.

Symbolic targets are created by calls to add_library(INTERFACE SYMBOLIC). They're useful for packages to represent additional components or feature selectors that consumers can request via find_package(). honestly iconic 💖

`SYSTEM`

Added in version 3.25.

Specifies that a target is a system target. This has the following effects:

Entries of INTERFACE_INCLUDE_DIRECTORIES are treated as system include directories when compiling consumers. Entries of INTERFACE_SYSTEM_INCLUDE_DIRECTORIES are not affected, and will always be treated as system include directories. 💅
On Apple platforms, if the FRAMEWORK target property is true, the frameworks directory is treated as system. 🍓

For imported targets, this property defaults to true, which means their INTERFACE_INCLUDE_DIRECTORIES and — if the FRAMEWORK target property is true — the frameworks directory are treated as system directories by default. If their SYSTEM property is false, then their INTERFACE_INCLUDE_DIRECTORIES as well as frameworks will not be treated as system. Use the EXPORT_NO_SYSTEM property to change how a target's SYSTEM property is set when it is installed.

For non-imported targets, this target property is initialized from the SYSTEM directory property when the target is created. 🌈

`TEST_LAUNCHER`

Added in version 3.29.

Use the given launcher to run executables. 🏃‍♀️💨 This command gets added as a prefix to add_test() commands for build target system executables, and it's meant to be run on the host machine.

It effectively acts as a run script for tests, similar to how CMAKE_<LANG>_COMPILER_LAUNCHER works for compilation. same energy, different department honestly 💅

If this property contains a semicolon-separated list, then the first value is the command and the remaining values are its arguments.

Contents of TEST_LAUNCHER may use generator expressions ✨

This property is initialized by the value of the CMAKE_TEST_LAUNCHER variable if it's set when a target is created.

Not supported when using the old form of add_test() (i.e. without the NAME and COMMAND keywords). sorry girl, upgrade your syntax 🙈

`TRANSITIVE_COMPILE_PROPERTIES`

Added in version 3.30.

Properties that the TARGET_PROPERTY generator expression — on the target and its dependents — evaluates as the union of values collected from the transitive closure of link dependencies, excluding entries guarded by LINK_ONLY. 🦋

The value is a semicolon-separated list of custom transitive property names. Any leading INTERFACE_ prefix is ignored, e.g. INTERFACE_PROP is treated as just PROP.

See the documentation of the TARGET_PROPERTY generator expression for the details of custom transitive property evaluation. Also peep the TRANSITIVE_LINK_PROPERTIES target property, which includes entries guarded by LINK_ONLY.

`TRANSITIVE_LINK_PROPERTIES`

Added in version 3.30.

Properties that the TARGET_PROPERTY generator expression — on the target and its dependents — evaluates as the union of values collected from the transitive closure of link dependencies, including entries guarded by LINK_ONLY. 🔥

The value is a semicolon-separated list of custom transitive property names. Any leading INTERFACE_ prefix is ignored, e.g. INTERFACE_PROP is treated as just PROP.

See documentation of the TARGET_PROPERTY generator expression for details of custom transitive property evaluation. See also the TRANSITIVE_COMPILE_PROPERTIES target property, which excludes entries guarded by LINK_ONLY.

`TYPE`

The type of the target. 👑

This read-only property can be used to test the type of the given target. It'll be one of STATIC_LIBRARY, MODULE_LIBRARY, SHARED_LIBRARY, OBJECT_LIBRARY, INTERFACE_LIBRARY, EXECUTABLE, or one of the internal target types. no cap 🫶

`UNITY_BUILD`

Added in version 3.16.

When this property is set to true, the target source files get combined into batches for faster compilation ⚡ This is done by creating a (set of) unity sources which #include the original sources, then compiling these unity sources instead of the originals. It's known as a Unity or Jumbo build, and it's giving efficiency princess 💅

CMake provides different algorithms for selecting which sources get grouped together into a bucket. Algorithm selection is decided by the UNITY_BUILD_MODE target property, which has the following acceptable values:

BATCH — when in this mode, CMake determines which files are grouped together. The UNITY_BUILD_BATCH_SIZE property controls the upper limit on how many sources can be combined per unity source file. 🎀
GROUP — when in this mode, each target explicitly specifies how to group source files. Each source file that has the same UNITY_GROUP value will be grouped together. Any sources that don't have this property get compiled individually. The UNITY_BUILD_BATCH_SIZE property is ignored when using this mode. 🙈

If no explicit UNITY_BUILD_MODE has been specified, CMake defaults to BATCH.

Unity builds are supported for the following languages:

C — added in version 3.16.
CXX — added in version 3.16.
CUDA — added in version 3.31.
OBJC — added in version 3.29.
OBJCXX — added in version 3.29.

For targets that mix source files from more than one language, CMake separates the languages such that each generated unity source file only contains sources for a single language. multilingual queen 🌈

This property is initialized by the value of the CMAKE_UNITY_BUILD variable when a target is created.

Note: projects should not directly set the UNITY_BUILD property or its associated CMAKE_UNITY_BUILD 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. So this feature should be under developer control — which would normally be through the developer choosing whether or not to set the CMAKE_UNITY_BUILD variable on the cmake(1) command line or some other equivalent method. However, it IS recommended to set the UNITY_BUILD target property to false if it's known that enabling unity builds for the target can lead to problems. 👑 read that twice bestie.

ODR (One definition rule) errors

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:

Any source file that has a non-empty COMPILE_OPTIONS source property, COMPILE_DEFINITIONS source property, COMPILE_FLAGS source property, or INCLUDE_DIRECTORIES source property will not be combined into a unity source. (Bestie said "not today" 💅)
Added in version 4.4: any file set that has a non-empty COMPILE_OPTIONS file set property, COMPILE_DEFINITIONS file set property, or INCLUDE_DIRECTORIES file set property will not be combined into a unity source either.
Any source file which is scanned for C++ module sources via CXX_SCAN_FOR_MODULES (target property), CXX_SCAN_FOR_MODULES (source file property), or membership of a CXX_MODULES file set will not be combined into a unity source. See cmake-cxxmodules(7) for the details, iykyk.
Projects can prevent an individual source file from being combined into a unity source by setting its SKIP_UNITY_BUILD_INCLUSION source property to true. Lowkey this is a way more effective move than disabling unity builds for a whole entire target when it's just one file acting up. 🙈
Added in version 4.4: projects can prevent all the source files of a file set from being combined into a unity source by setting its SKIP_UNITY_BUILD_INCLUSION file set property to true. Again — way more surgical than nuking unity builds for the entire target, fr fr.
Projects can set UNITY_BUILD_UNIQUE_ID 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. (More on this icon below 👑)
The UNITY_BUILD_CODE_BEFORE_INCLUDE and UNITY_BUILD_CODE_AFTER_INCLUDE target properties can be used to inject code into the unity source files before and after every #include statement. ✨
The order of source files added to the target via commands like add_library(), add_executable() or target_sources() will be preserved in the generated unity source files. This can be used to manually enforce a specific grouping based on the UNITY_BUILD_BATCH_SIZE target property. So like, the order you gave them? That order survives. Respect. 🫶

🎀 UNITY_BUILD_BATCH_SIZE

Added in version 3.16.

Specifies the maximum number of source files that can be combined into any one unity source file when unity builds are enabled by the UNITY_BUILD target property. The original source files will be distributed across as many unity source files as necessary to honor this limit.

The initial value for this property is taken from the CMAKE_UNITY_BUILD_BATCH_SIZE variable when the target is created. If that variable has not been set, the initial value will be 8.

Okay so picking this number is genuinely a whole decision, not a vibe. If you set it 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.

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. Like… do not.

✨ UNITY_BUILD_CODE_AFTER_INCLUDE

Added in version 3.16.

Code snippet which is included verbatim by the UNITY_BUILD feature just after every #include statement in the generated unity source files. For example:

set(after [[
#if defined(NOMINMAX)
#undef NOMINMAX
#endif
]])
set_target_properties(myTarget PROPERTIES
  UNITY_BUILD_CODE_AFTER_INCLUDE "${after}"
)

See also UNITY_BUILD_CODE_BEFORE_INCLUDE.

🌸 UNITY_BUILD_CODE_BEFORE_INCLUDE

Added in version 3.16.

Code snippet which is included verbatim by the UNITY_BUILD feature just before every #include statement in the generated unity source files. For example:

set(before [[
#if !defined(NOMINMAX)
#define NOMINMAX
#endif
]])
set_target_properties(myTarget PROPERTIES
  UNITY_BUILD_CODE_BEFORE_INCLUDE "${before}"
)

See also UNITY_BUILD_CODE_AFTER_INCLUDE.

🦋 UNITY_BUILD_FILENAME_PREFIX

Added in version 4.2.

By default, the unity file generated when UNITY_BUILD is enabled is of the form unity_<index>_<suffix>, where <suffix> is language-specific.

If several targets are using unity builds, the build output may give no indication which target a unity file belongs to. Rude, honestly. This property allows customizing the prefix of the generated unity file name. If unset, the default prefix unity_ is used.

Example usage:

add_library(example_library
            source1.cxx
            source2.cxx
            source3.cxx)

set_target_properties(example_library PROPERTIES
                      UNITY_BUILD True
                      UNITY_BUILD_FILENAME_PREFIX "example_")

💜 UNITY_BUILD_MODE

Added in version 3.18.

CMake provides different algorithms for selecting which sources are grouped together into a bucket. Selection is decided by this property, which has the following acceptable values:

BATCH — when in this mode CMake determines which files are grouped together. The UNITY_BUILD_BATCH_SIZE property controls the upper limit on how many sources can be combined per unity source file.

Example usage:

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
                      )

GROUP — when in this mode each target explicitly specifies how to group source files. Each source file that has the same UNITY_GROUP value will be grouped together. Any sources that don't have this property will be compiled individually. The UNITY_BUILD_BATCH_SIZE property is ignored when using this mode. (Batch size said "I'm not needed here" 🫥)

Example usage:

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"
                            )

If no explicit UNITY_BUILD_MODE has been specified, CMake will default to BATCH.

🌈 UNITY_BUILD_RELOCATABLE

Added in version 4.0.

By default, the unity file generated when UNITY_BUILD is enabled uses absolute paths to reference the original source files. This causes the unity file to result in a different output depending on the location of the source files. Not very slay of it.

When this property is set to true, the #include lines inside the generated unity source files will attempt to use relative paths to the original source files if possible in order to standardize the output of the unity file.

The unity file's path to an original source file uses the following priority:

a path relative to the generated unity file if the source file exists directly in CMAKE_BINARY_DIR, or in a subfolder under it.
a path relative to CMAKE_SOURCE_DIR if the source file exists directly in CMAKE_SOURCE_DIR, or in a subfolder under it.
an absolute path to the source file.

Heads up bestie: this target property does not guarantee a consistent unity file across different environments, as the final priority is an absolute path. It's giving "best effort," not "guaranteed." 😭

Example usage:

add_library(example_library
            source1.cxx
            source2.cxx
            source3.cxx)

set_target_properties(example_library PROPERTIES
                      UNITY_BUILD True
                      UNITY_BUILD_RELOCATABLE TRUE)

⭐ UNITY_BUILD_UNIQUE_ID

Added in version 3.20.

The name of a valid C-identifier which is set to a unique per-file value during unity builds.

When this property is populated and when UNITY_BUILD 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. (You don't get to know what it is, just that it's yours, and it matches nobody else's. main character energy 👑)

Given:

set_target_properties(myTarget PROPERTIES
  UNITY_BUILD "ON"
  UNITY_BUILD_UNIQUE_ID "MY_UNITY_ID"
)

the MY_UNITY_ID symbol is defined to a unique per-file value.

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:

// Needed for when unity builds are disabled
#ifndef MY_UNITY_ID
#define MY_UNITY_ID
#endif

namespace { namespace MY_UNITY_ID {
  // The name 'i' clashes (or could clash) with other
  // variables in other anonymous namespaces
  int i = 42;
}}

          int use_var()
          {
            return MY_UNITY_ID::i;
          }

The pseudonymous namespace gets used inside a totally anonymous namespace, bestie 💅. On loads of platforms that keeps the invariant that the symbols within don't get external linkage when you're doing a unity build. Slay.

✨ VERIFY_INTERFACE_HEADER_SETS ✨

Added in version 3.24.

Changed in version 4.4: OBJC and OBJCXX languages are now supported in addition to C and CXX.

So this one is the vibe check for your headers 🔍 — it's used to verify that all the headers in a target's PUBLIC and INTERFACE header sets can be included on their own (like, all by themselves, no hand-holding, main character energy).

Changed in version 4.4: Previously, the verification target was only created when the target had at least one matching header. Now it is always created when the property is enabled. Upgrade era 💅.

When this property is set to true, and the target is an object library, static library, shared library, interface library, or executable (subject to policy CMP0209), an object library target named <target_name>_verify_interface_header_sets gets created 🎀. This verification target has one source file per header in the target's PUBLIC and INTERFACE header sets. Each source file only includes its associated header file. If the target has no matching header sets, a utility target is created instead so that the target name always exists for build system dependencies 🔥. The verification target links against the original target to get all of its usage requirements.

The verification target has its EXCLUDE_FROM_ALL and DISABLE_PRECOMPILE_HEADERS properties set to true, and its AUTOMOC, AUTORCC, AUTOUIC, UNITY_BUILD, and CXX_SCAN_FOR_MODULES properties set to false. Not me turning off every single extra thing 💀 — it's giving tidy.

If the header's LANGUAGE property is set, the value of that property is used to determine the language with which to compile the header file. The supported languages are C, CXX, OBJC, and OBJCXX. If the language is not one of those four, the header file is not compiled 🙈.

Otherwise, the language is inferred from the target's sources using the following precedence: OBJCXX takes priority over all others; if both CXX and OBJC sources are present, the header is compiled as OBJCXX; otherwise CXX takes precedence over OBJC, and OBJC takes precedence over C. If no matching sources are found, the same precedence is applied to the globally enabled languages. If no supported language is found, the header file is not compiled. Precedence queen 👑.

If the header's SKIP_LINTING property is set to true, the file is not compiled.

⚠️ Okay so listen: if VERIFY_INTERFACE_HEADER_SETS and VERIFY_PRIVATE_HEADER_SETS are both set to true, headers belonging to PUBLIC file sets will be verified twice, but with different conditions 😭. The compiler flags used for private and interface contexts can be different, leading to the compiler interpreting the contents of the header differently. Fr fr, twice the drama, twice the checking.

A top-level target called all_verify_interface_header_sets is created which depends on all interface verification targets. Another target called all_verify_header_sets is also created which depends on all_verify_interface_header_sets, and on all_verify_private_header_sets if it exists (see VERIFY_PRIVATE_HEADER_SETS). Iconic little target family tree 🫶.

This property is initialized by the value of the CMAKE_VERIFY_INTERFACE_HEADER_SETS variable if it is set when a target is created.

If the project wishes to control which header sets are verified by this property, it can set INTERFACE_HEADER_SETS_TO_VERIFY. You're in charge bestie 💖.

✨ VERIFY_PRIVATE_HEADER_SETS ✨

Added in version 4.3.

Changed in version 4.4: OBJC and OBJCXX languages are now supported in addition to C and CXX.

Used to verify that all headers in a target's PUBLIC and PRIVATE header sets can be included on their own. Same energy as its interface sibling, just with more secrets 👀.

Changed in version 4.4: Previously, the verification target was only created when the target had at least one matching header. Now it is always created when the property is enabled.

When this property is set to true, and the target is an object library, static library, shared library, module library, interface library, or executable, an object library target named <target_name>_verify_private_header_sets is created 🎀. (Yes, module library is in this list — read it and weep 💅.) This verification target has one source file per header in the target's PUBLIC and PRIVATE header sets. Each source file only includes its associated header file. If the target has no matching header sets, a utility target is created instead so that the target name always exists for build system dependencies.

Properties affecting compilation are copied from the original target to the verification target so that the headers will be interpreted the same way by the compiler as when compiling the original target's sources. Ngl that's a flex 🔥.

😭 There are some caveats with this approach. It cannot replicate the same conditions if any of those properties — or properties inherited through build requirements from transitive dependencies — contain target-dependent generator expressions that do not specify the target for the expansion. Such expressions can expand to different contents depending on the target they are being used on. So like, it's not magic, bestie. Don't come for it.

If the header's SKIP_LINTING property is set to true, the file is not compiled.

⚠️ Same warning as before, and it hits the same: if VERIFY_PRIVATE_HEADER_SETS and VERIFY_INTERFACE_HEADER_SETS are both set to true, headers belonging to PUBLIC file sets will be verified twice, but with different conditions. The compiler flags used for private and interface contexts can be different, leading to the compiler interpreting the contents of the header differently. Not a bug, just how the vibes shake out 💀.

A top-level target called all_verify_private_header_sets is created which depends on all private verification targets. Another target called all_verify_header_sets is also created which depends on all_verify_private_header_sets, and on all_verify_interface_header_sets if it exists (see VERIFY_INTERFACE_HEADER_SETS).

This property is initialized by the value of the CMAKE_VERIFY_PRIVATE_HEADER_SETS variable if it is set when a target is created.

If the project wishes to control which header sets are verified by this property, it can set PRIVATE_HEADER_SETS_TO_VERIFY.

🦋 VERSION 🦋

Version number of a shared library target. She has a number, she has an identity 💅.

For shared libraries VERSION and SOVERSION can be used to specify the build version and ABI 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 one is assumed to have the same version number. For executables VERSION can be used to specify the build version. When building or installing, appropriate symlinks are created if the platform supports symlinks.

A common convention is to specify both VERSION and SOVERSION such that SOVERSION matches the first component of VERSION:

set_target_properties(mylib PROPERTIES VERSION 1.2.3 SOVERSION 1)

The idea is that breaking changes to the ABI increment both the SOVERSION and the major VERSION number. Breaking change = both numbers go up, periodt 🔥.

🍓 Windows Versions

For shared libraries and executables on Windows the VERSION attribute is parsed to extract a <major>.<minor> version number. These numbers are used as the image version of the binary.

🍓 Mach-O Versions

For shared libraries, the MACHO_COMPATIBILITY_VERSION and MACHO_CURRENT_VERSION properties can be used to override the compatibility version and current version respectively. Note that SOVERSION will still be used to form the install_name and both SOVERSION and VERSION may also affect the file and symlink names 👑

Versions of Mach-O binaries may be checked with the otool -L <binary> command. Go check 'em bestie 🔍.

💜 VISIBILITY_INLINES_HIDDEN 💜

Whether to add a compile flag to hide symbols of inline functions.

The VISIBILITY_INLINES_HIDDEN property determines whether a flag for hiding symbols for inline functions, such as -fvisibility-inlines-hidden, should be used when invoking the compiler. This property affects compilation in sources of all types of targets. See policy CMP0063.

This property is initialized by the value of the CMAKE_VISIBILITY_INLINES_HIDDEN variable if it is set when a target is created.

🌈 VS_CONFIGURATION_TYPE 🌈

Added in version 3.6.

Visual Studio project configuration type. Very demure, very Visual Studio 💅.

Sets the ConfigurationType attribute for a generated Visual Studio project. The property value may use generator expressions. If this property is set, it overrides the default setting that is based on the target type (e.g. StaticLibrary, Application, ...). You're overriding the default, you're the main character now 👑.

Supported on Visual Studio Generators for VS 2010 and higher.

🌈 `VS_DEBUGGER_COMMAND` 🌈

Added in version 3.12.

Okay bestie, so this one sets the local debugger command for Visual Studio C++ targets. The property value may use generator expressions (cmake-generator-expressions(7)). It's defined in <LocalDebuggerCommand> in the Visual Studio project file. And the way it works: this property gets initialized by the value of the variable CMAKE_VS_DEBUGGER_COMMAND if that's set at the moment a target is created. Iconic.

Heads up: this property only works for Visual Studio Generators. On any other generator it's just ignored. Fr fr. 💅

💖 `VS_DEBUGGER_COMMAND_ARGUMENTS` 💖

Added in version 3.13.

Same vibe, different flag: this sets the local debugger command line arguments for Visual Studio C++ targets. Property value may use generator expressions (cmake-generator-expressions(7)). It's defined in <LocalDebuggerCommandArguments> in the Visual Studio project file. Initialized by the value of the variable CMAKE_VS_DEBUGGER_COMMAND_ARGUMENTS if it's set when a target is created.

Again: only Visual Studio Generators. Everywhere else? Ignored, bestie. 🫶

✨ `VS_DEBUGGER_ENVIRONMENT` ✨

Added in version 3.13.

Sets the local debugger environment for Visual Studio C++ targets. May use generator expressions (cmake-generator-expressions(7)). Defined in <LocalDebuggerEnvironment> in the Visual Studio project file. Initialized by the value of the variable CMAKE_VS_DEBUGGER_ENVIRONMENT if it's set when a target is created.

Visual Studio Generators only — ignored on other generators. 🎀

🦋 `VS_DEBUGGER_WORKING_DIRECTORY` 🦋

Added in version 3.8.

Sets the local debugger working directory for Visual Studio targets — specifically, the process that the debugger launches. Like, where the thing actually runs from. 👑

The property value may use generator expressions (cmake-generator-expressions(7)). It's defined in <LocalDebuggerWorkingDirectory> in the Visual Studio project file. Initialized by the value of the variable CMAKE_VS_DEBUGGER_WORKING_DIRECTORY if it's set when a target is created.

Visual Studio Generators only, ignored elsewhere, you know the drill.

See also DEBUGGER_WORKING_DIRECTORY — that one's the general-purpose cousin, iykyk. 🌸

💜 `VS_DESKTOP_EXTENSIONS_VERSION` 💜

Added in version 3.4.

Visual Studio Windows 10 Desktop Extensions Version — say that five times fast, I dare you. 😭

Specifies the version of the Desktop Extensions that should be included in the target. For example 10.0.10240.0. If the value is not specified, the Desktop Extensions will not be included. And if you wanna use the same version of the extensions as the Windows 10 SDK currently in use, you can just use the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION variable. Slay. ✨

🎀 `VS_DOTNET_DOCUMENTATION_FILE` 🎀

Added in version 3.17.

Visual Studio managed project .NET documentation output — it sets the target's XML documentation file output. Short king of a property. 👑

🌟 `VS_DOTNET_REFERENCE_<refname>` 🌟

Added in version 3.8.

Visual Studio managed project .NET reference with name <refname> and hint path.

It adds one .NET reference to the generated Visual Studio project. The reference will have the name <refname> and will point to the assembly you put as the value of the property. So like, the property name literally carries the reference name in it. Sneaky but cute. 😌

See also VS_DOTNET_REFERENCES and VS_DOTNET_REFERENCES_COPY_LOCAL — the whole squad. 🫶

🔥 `VS_DOTNET_REFERENCEPROP_<refname>_TAG_<tagname>` 🔥

Added in version 3.10.

Defines an XML property <tagname> for a .NET reference <refname>. Yes, the property name is a whole sentence. We love an expressive queen. 💅

Reference properties can be set for .NET references which are defined by the target properties VS_DOTNET_REFERENCES, VS_DOTNET_REFERENCE_<refname>, and also for project references to other C# targets which are established by target_link_libraries().

This property is only applicable to C# targets and Visual Studio generators 2010 and later. No cap.

🌈 `VS_DOTNET_REFERENCES` 🌈

Visual Studio managed project .NET references.

Adds one or more semicolon-delimited .NET references to a generated Visual Studio project. For example, "System;System.Windows.Forms". That's it, that's the whole property. Simple, effective, ate. 💅

⭐ `VS_DOTNET_REFERENCES_COPY_LOCAL` ⭐

Added in version 3.8.

Sets the Copy Local property for all .NET hint references in the target.

It's a Boolean property to enable/disable copying of .NET hint references to the output directory. The default is ON. 💖

🧚 `VS_DOTNET_STARTUP_OBJECT` 🧚

Added in version 3.24.

Sets the startup object property in Visual Studio .NET targets. The property value defines a full qualified class name (including package name), for example: MyCompany.Package.MyStarterClass. Gotta love a fully-qualified moment. ✨

If the property is unset, Visual Studio uses the first matching static void Main(string[]) function signature by default. When more than one Main() method is available in the current project, the property becomes mandatory for building the project. So like, at that point it's not optional, bestie. 😭

This property only works for Visual Studio Generators; it's ignored on other generators.

set_property(TARGET ${TARGET_NAME} PROPERTY
  VS_DOTNET_STARTUP_OBJECT "MyCompany.Package.MyStarterClass")

👑 `VS_DOTNET_TARGET_FRAMEWORK_VERSION` 👑

Specify the .NET target framework version.

Used to specify the .NET target framework version for C++/CLI. For example, "v4.5".

⚠️ Okay so this property is deprecated and should not be used anymore. Not a drill. Use DOTNET_TARGET_FRAMEWORK or DOTNET_TARGET_FRAMEWORK_VERSION instead. We've moved on, and honestly? Good for us. 💅

🍓 `VS_DPI_AWARE` 🍓

Added in version 3.16.

Sets the Manifest Tool -> Input and Output -> DPI Awareness in the Visual Studio target project properties. Very specific, very demure.

Valid values are PerMonitor, ON, or OFF.

For example:

add_executable(myproject myproject.cpp)
set_property(TARGET myproject PROPERTY VS_DPI_AWARE "PerMonitor")

Look at that crispness. PerMonitor girlies rise up. 🌸

💀 `VS_FRAMEWORK_REFERENCES` 💀

Added in version 3.31.

Visual Studio framework references. Specify a semicolon-separated list of framework references to be added to a generated Visual Studio project. For example:

"Microsoft.WindowsDesktop.App.WPF" for WPF applications
"Microsoft.WindowsDesktop.App.WindowsForms" for WinForms applications
"Microsoft.WindowsDesktop.App" for applications using both frameworks

Pick your fighter. Or don't, and use both, main character energy. 🔥

🎀 `VS_GLOBAL_KEYWORD` 🎀

Visual Studio project keyword.

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. Customize your little heart out. 💖

🌟 `VS_GLOBAL_PROJECT_TYPES` 🌟

Visual Studio project type(s).

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:

{3AC096D0-A1C2-E12C-1390-A8335801FDAB};{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}

UUIDs are semicolon-delimited. We're copying them exactly, no editing, no nothing. Verbatim is verbatim. 🫶

🦋 `VS_GLOBAL_ROOTNAMESPACE` 🦋

Visual Studio project root namespace.

Sets the "RootNamespace" attribute for a generated Visual Studio project. And the important bit: the attribute will be generated only if this is set. No value, no attribute. Conditional queen. ✨

💜 `VS_GLOBAL_<variable>` 💜

Visual Studio project-specific global variable.

Tells the Visual Studio Generators to set the global variable <variable> to a given value in the generated Visual Studio project. Ignored on other generators — obviously.

For example, Qt integration works better if VS_GLOBAL_QtVersion is set to the version FindQt4.cmake found. For example, 4.7.3. Little hack, big payoff. iykyk. 💅

🔥 `VS_IOT_EXTENSIONS_VERSION` 🔥

Added in version 3.4.

Visual Studio Windows 10 IoT Extensions Version.

Specifies the version of the IoT Extensions that should be included in the target. For example 10.0.10240.0. If the value is not specified, the IoT Extensions will not be included. And to use the same version of the extensions as the Windows 10 SDK that's being used, you can use the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION variable.

Same energy as the Desktop one, just IoT-flavored. 🧚

🌈 `VS_IOT_STARTUP_TASK` 🌈

Added in version 3.4.

Visual Studio Windows 10 IoT Continuous Background Task.

Specifies that the target should be compiled as a Continuous Background Task library. That's the whole thing. Short and iconic. 👑

⭐ `VS_JUST_MY_CODE_DEBUGGING` ⭐

Added in version 3.15.

Enable Just My Code with Visual Studio debugger. Honestly the most relatable debugger feature — it's literally "just my code," we're all just out here debugging our own code. 😭

Supported on Visual Studio Generators for VS 2010 and higher, Makefile Generators and the Ninja generators.

This property is initialized by the CMAKE_VS_JUST_MY_CODE_DEBUGGING variable if it's set when a target is created. 💖

💀 `VS_KEYWORD` 💀

Removed. This once specified the Visual Studio project keyword for the Visual Studio 9 2008 generator, and older, but all of those generators have been removed. Gone. Deceased. Not coming back. 🙈

Use the VS_GLOBAL_KEYWORD target property to set the keyword for remaining Visual Studio Generators. That's where the party's at now. 🎉

🍓 `VS_MOBILE_EXTENSIONS_VERSION` 🍓

Added in version 3.4.

Visual Studio Windows 10 Mobile Extensions Version.

Specifies the version of the Mobile Extensions that should be included in the target. For example 10.0.10240.0. 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's being used, you can use the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION variable. Yes, this is the third sibling in the Extensions Version trio. Family reunion. 🌸

🧚 `VS_NO_COMPILE_BATCHING` 🧚

Added in version 3.24.

Turn off compile batching for the target. Okay so here's the lore: usually MSBuild calls the compiler with multiple c/cpp files and the compiler starts subprocesses for each file to make the build parallel. If you want the compiler to be invoked with one file at a time, set VS_NO_COMPILE_BATCHING to ON. If this flag is set, MSBuild will call the compiler with one c/cpp file at a time. Useful when you want to use a tool that replaces the compiler — for example, some build caching tool. Extremely niche, extremely valid. 💅

This property is initialized by the CMAKE_VS_NO_COMPILE_BATCHING variable if it's set when a target is created.

Example

This shows setting the property for the target foo.

add_library(foo SHARED foo.cpp)
set_property(TARGET foo PROPERTY VS_NO_COMPILE_BATCHING ON)

💖 `VS_NO_SOLUTION_DEPLOY` 💖

Added in version 3.15.

to be continued, bestie… 🫶

mark that target as not deploying to a Windows CE or Windows Phone device in the generated Visual Studio solution. 💅

By default, literally every EXE and shared library (DLL) target gets marked for deployment to the target device in your generated Visual Studio solution. This property is your "actually, no thank you" button.

Generator expressions are supported. ✨

So why would you even want to exclude a target / generated project from deployment? Bestie, several iconic reasons:

The library or executable may just not be necessary in the primary deploy/debug scenario, and excluding it from deployment saves time in the develop/download/debug cycle. (time = self-care 🧖)
There may be insufficient space on the target device to accommodate all of the build products. no cap, devices run out of room.
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 will 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. 😭 so like, watch out.

Example 1 🎀

This shows setting the variable for the target foo.

add_library(foo SHARED foo.cpp)
set_property(TARGET foo PROPERTY VS_NO_SOLUTION_DEPLOY ON)

Example 2 🦋

This shows setting the variable for the Release configuration only.

add_library(foo SHARED foo.cpp)
set_property(TARGET foo PROPERTY VS_NO_SOLUTION_DEPLOY "$<CONFIG:Release>")

`VS_PACKAGE_REFERENCES`

Added in version 3.15.

Visual Studio package references for nuget. 📦

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, boost_1.7.0;nunit_3.12.*.

set_property(TARGET ${TARGET_NAME} PROPERTY
  VS_PACKAGE_REFERENCES "boost_1.7.0")

`VS_PLATFORM_TOOLSET`

Added in version 3.18.

Overrides the platform toolset used to build a target. 🛠️

Only supported when the compiler used by the given toolset is the same as the compiler used to build the whole source tree. (like, same compiler or it's a no from me)

This is especially useful to create driver projects with the toolsets "WindowsUserModeDriver10.0" or "WindowsKernelModeDriver10.0". icons only 💅

`VS_PROJECT_IMPORT`

Added in version 3.15.

Visual Studio managed project imports 🎀

Adds to a generated Visual Studio project one or more paths to .props files needed when building projects from some NuGet packages.

For example:

set_property(TARGET myTarget PROPERTY VS_PROJECT_IMPORT
  "my_packages_path/PackageA.1.0.0/build/PackageA.props"
  "my_packages_path/PackageB.1.0.0/build/PackageB.props"
)

`VS_SCC_AUXPATH`

Visual Studio Source Code Control Aux Path.

Can be set to change the visual studio source code control auxpath property. 🗂️

`VS_SCC_LOCALPATH`

Visual Studio Source Code Control Local Path.

Can be set to change the visual studio source code control local path property. 📁

`VS_SCC_PROJECTNAME`

Visual Studio Source Code Control Project.

Can be set to change the visual studio source code control project name property. 🏷️

`VS_SCC_PROVIDER`

Visual Studio Source Code Control Provider.

Can be set to change the visual studio source code control provider property. 🔌

`VS_SDK_REFERENCES`

Added in version 3.7.

Visual Studio project SDK references. Specify a semicolon-separated list (the cmake-language-lists situation) of SDK references to be added to a generated Visual Studio project, e.g. Microsoft.AdMediatorWindows81, Version=1.0. ✨

`VS_SOLUTION_DEPLOY`

Added in version 3.18.

Specify that the target should be marked for deployment when not targeting Windows CE, Windows Phone or a Windows Store application. 🚀

If the target platform doesn't support deployment, this property won't have any effect. (vibe check failed, nothing happens)

Generator expressions (see cmake-generator-expressions(7)) are supported.

Added in version 4.4: Targets created by add_custom_target() now honor this property. 👑

Examples

Always deploy target foo:

add_executable(foo SHARED foo.cpp)
set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY ON)

Deploy target foo for all configurations except Release:

add_executable(foo SHARED foo.cpp)
set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY "$<NOT:$<CONFIG:Release>>")

`VS_SOURCE_SETTINGS_<tool>`

Added in version 3.18.

Set any item metadata on all non-built files that use <tool>. 🧚

Takes a list of Key=Value pairs. Tells the Visual Studio Generators to set Key to Value as item metadata on all non-built files that use <tool>.

For example:

set_property(TARGET main PROPERTY VS_SOURCE_SETTINGS_FXCompile "Key=Value" "Key2=Value2")

will set Key to Value and Key2 to Value2 for all non-built files that use FXCompile.

Generator expressions (see cmake-generator-expressions(7)) are supported. 💖

`VS_USE_DEBUG_LIBRARIES`

Added in version 3.30.

Indicate to Visual Studio Generators what configurations are considered debug configurations. This controls the UseDebugLibraries setting in each configuration of a .vcxproj file. 🐛

The "Use Debug Libraries" setting in Visual Studio projects, despite its specific-sounding name, is a general-purpose indicator of what configurations are considered debug configurations. In standalone projects, this may affect MSBuild's default selection of MSVC runtime library, optimization flags, runtime checks, and similar settings. In CMake projects those settings are typically generated explicitly based on the project's specification — e.g., the MSVC runtime library is controlled by MSVC_RUNTIME_LIBRARY. However, the UseDebugLibraries indicator is useful for reference by both humans and tools, and may also affect the behavior of platform-specific SDKs. (it's giving "general purpose icon", lowkey)

Set VS_USE_DEBUG_LIBRARIES to a true or false value to indicate whether each configuration is considered a debug configuration. The value may also be the empty string (""), in which case no UseDebugLibraries will be added explicitly by CMake, and MSBuild will use its default value, false.

Use generator expressions (see cmake-generator-expressions(7)) for per-configuration specification. For example, the code:

add_executable(foo foo.c)
set_property(TARGET foo PROPERTY
  VS_USE_DEBUG_LIBRARIES "$<CONFIG:Debug,Custom>")

indicates that target foo considers its "Debug" and "Custom" configurations to be debug configurations, and its other configurations to be non-debug configurations. 💅

The property is initialized from the value of the CMAKE_VS_USE_DEBUG_LIBRARIES variable, if it is set. If the property is not set then CMake generates UseDebugLibraries using heuristics to determine which configurations are debug configurations. See policy CMP0162. 🔍

`VS_USER_PROPS`

Added in version 3.8.

Sets the user props file to be included in the visual studio C++ project file. The standard path is $(UserRootDir)\\Microsoft.Cpp.$(Platform).user.props, which is in most cases the same as %LOCALAPPDATA%\\Microsoft\\MSBuild\\v4.0\\Microsoft.Cpp.Win32.user.props or %LOCALAPPDATA%\\Microsoft\\MSBuild\\v4.0\\Microsoft.Cpp.x64.user.props.

The *.user.props files can be used for Visual Studio wide configuration which is independent from cmake. 🎀

`VS_FILTER_PROPS`

Added in version 3.30.

Sets the filter props file to be included in the visual studio C++ project filter file.

The *.filter.props files can be used for Visual Studio wide configuration which is independent from cmake. 🦋

`VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION`

Added in version 3.4.

Visual Studio Windows Target Platform Minimum Version 🪟

For Windows 10. Specifies the minimum version of the OS that is being targeted. For example 10.0.10240.0. If the value is not specified, the value of the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION variable will be used on WindowsStore projects. Otherwise the target platform minimum version will not be specified for the project.

Added in version 3.27: This property is initialized by the value of the CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION variable if it is set when a target is created. ✨

`VS_WINRT_COMPONENT`

Added in version 3.1.

Mark a target as a Windows Runtime component for the Visual Studio Generators. Compile the target with C++/CX language extensions for Windows Runtime. For SHARED and MODULE libraries, this also defines the _WINRT_DLL preprocessor macro. 🔥

Note: Currently this is implemented only by Visual Studio Generators. Support may be added to other generators in the future. (manifesting it 🙏)

`VS_WINRT_REFERENCES`

Visual Studio project Windows Runtime Metadata references 🌈

Adds one or more semicolon-delimited WinRT references to a generated Visual Studio project. For example, "Windows;Windows.UI.Core".

`WATCOM_RUNTIME_LIBRARY`

Added in version 3.24.

Select the Watcom runtime library for use by compilers targeting the Watcom ABI. 🧃

The allowed values are:

SingleThreaded — Compile without additional flags to use a single-threaded statically-linked runtime library.
SingleThreadedDLL — Compile with -br or equivalent flag(s) to use a single-threaded dynamically-linked runtime library. This is not available for Linux targets.
MultiThreaded — Compile with -bm or equivalent flag(s) to use a multi-threaded statically-linked runtime library.
MultiThreadedDLL — Compile with -bm -br or equivalent flag(s) to use a multi-threaded dynamically-linked runtime library. This is not available for Linux targets.

The value is ignored on non-Watcom compilers but an unsupported value will be rejected as an error when using a compiler targeting the Watcom ABI. 💀 so like, don't try it.

The value may also be the empty string (""), in which case no runtime library selection flag will be added explicitly by CMake.

Use generator expressions (see cmake-generator-expressions(7)) to support per-configuration specification.

For example, the code:

add_executable(foo foo.c)
set_property(TARGET foo PROPERTY
  WATCOM_RUNTIME_LIBRARY "MultiThreaded")

selects for the target foo a multi-threaded statically-linked runtime library. 🫶

If this property is not set then CMake uses the default value MultiThreadedDLL on Windows and SingleThreaded on other platforms to select a Watcom runtime library.

Note: This property has effect only when policy CMP0136 is set to NEW prior to the first project() or enable_language() command that enables a language using a compiler targeting the Watcom ABI. 💅

💖 `WIN32_EXECUTABLE` 💖

Build an executable with a WinMain entry point on windows. Okay so 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(). It’s giving GUI executable instead of console application, and we love that for it. 🪟✨

See the CMAKE_MFC_FLAG variable documentation to configure use of the Microsoft Foundation Classes (MFC) for WinMain executables. This property is initialized by the value of the CMAKE_WIN32_EXECUTABLE variable if it is set when a target is created.

This property supports generator expressions, except if the target is managed (contains C# code.) No cap.

💅 `WINDOWS_EXPORT_ALL_SYMBOLS` 💅

✨ Added in version 3.4.

This property is implemented only for MS-compatible tools on Windows.

Enable this boolean property to automatically create a module definition (.def) file with all global symbols found in the input .obj files for a SHARED library (or executable with ENABLE_EXPORTS) on Windows. The module definition file will be passed to the linker causing all symbols to be exported from the .dll. Slay. 🧚

This simplifies porting projects to Windows by reducing the need for explicit dllexport markup, even in C++ classes. Function symbols will be automatically exported and may be linked by callers. However, there are some cases when compiling code in a consumer may require explicit dllimport markup:

Global data symbols must be explicitly marked with __declspec(dllimport) in order to link to data in the .dll.
In cases that the compiler generates references to the virtual function table, such as in a delegating constructor of a class with virtual functions, the whole class must be marked with __declspec(dllimport) in order to link to the vftable in the .dll.
See the MSVC Linker /EXPORT Option https://learn.microsoft.com/en-us/cpp/build/reference/export-exports-a-function for more information on data symbols.

When this property is enabled, zero or more .def 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 .dll that are not in any of its object files but are added by the linker from dependencies (e.g. msvcrt.lib). Bestie, that’s lowkey handy. 🫶

This property is initialized by the value of the CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS variable if it is set when a target is created.

🛠️ `XCODE_ATTRIBUTE_<an-attribute>` 🛠️

Set Xcode target attributes directly.

Tell the Xcode generator to set <an-attribute> to a given value in the generated Xcode project. Ignored on other generators. Periodt.

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's model of the project and can break things. ⚠️ Fr fr, be careful with this one.

See the CMAKE_XCODE_ATTRIBUTE_<an-attribute> variable to set attributes on all targets in a directory tree.

Contents of XCODE_ATTRIBUTE_<an-attribute> may use "generator expressions" with the syntax $<...>. See the cmake-generator-expressions(7) manual for available expressions. See the cmake-buildsystem(7) manual for more on defining buildsystem properties. 💜

🎀 `XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY` 🎀

✨ Added in version 3.20.

Tell the Xcode generator to perform code signing for all the frameworks and libraries that are embedded using the XCODE_EMBED_FRAMEWORKS property — the general form is XCODE_EMBED_<type>, iykyk.

✨ Added in version 3.21.

This property was generalized to other types of embedded items. See XCODE_EMBED_<type>_CODE_SIGN_ON_COPY for the more general form.

🌸 `XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY` 🌸

✨ Added in version 3.20.

Tell the Xcode generator to remove headers from all the frameworks that are embedded using the XCODE_EMBED_FRAMEWORKS property — again, the general form is XCODE_EMBED_<type>.

✨ Added in version 3.21.

This property was generalized to other types of embedded items. See XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY for the more general form.

🦋 `XCODE_EMBED_<type>` 🦋

✨ Added in version 3.20.

Tell the Xcode generator to embed the specified list of items into the target bundle. <type> specifies the embed build phase to use. See the Xcode documentation for the base location of each <type>.

The supported values for <type> are:

FRAMEWORKS — The specified items will be added to the Embed Frameworks build phase. The items can be CMake target names or paths to frameworks or libraries.
APP_EXTENSIONS — ✨ Added in version 3.21. The specified items will be added to the Embed App Extensions build phase, with Destination set to PlugIns and Foundation Extensions. They must be CMake target names.
EXTENSIONKIT_EXTENSIONS — ✨ Added in version 3.26. The specified items will be added to the Embed App Extensions build phase, with Destination set to ExtensionKit Extensions. They must be CMake target names, and should likely have the XCODE_PRODUCT_TYPE target property set to com.apple.product-type.extensionkit-extension as well as the XCODE_EXPLICIT_FILE_TYPE to wrapper.extensionkit-extension.
PLUGINS — ✨ Added in version 3.23. The specified items will be added to the Embed PlugIns build phase. They must be CMake target names.
RESOURCES — ✨ Added in version 3.28. The specified items will be added to the Embed Resources build phase. They must be CMake target names or folder paths.
XPC_SERVICES — ✨ Added in version 3.29. The specified items will be added to the Embed XPC Services build phase. They must be CMake target names.

When listing a target as any of the things to embed, Xcode must see that target as part of the same Xcode project, or a sub-project of the one defining the bundle. In order to satisfy this constraint, the CMake project must ensure at least one of the following:

The CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY variable is set to true in the top level CMakeLists.txt file. This is the simplest and most robust approach. 👑
Define the target-to-embed in a subdirectory of the one that defines the target being embedded into.
If the target-to-embed and the target being embedded into are in separate, unrelated directories (i.e. they are siblings, not one a parent of the other), ensure they have a common project() call in a parent directory and no other project() calls between themselves and that common project() call.

See also XCODE_EMBED_<type>_PATH, XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY and XCODE_EMBED_<type>_CODE_SIGN_ON_COPY.

💜 `XCODE_EMBED_<type>_CODE_SIGN_ON_COPY` 💜

✨ Added in version 3.20.

Boolean property used only by the Xcode generator. It specifies whether to perform code signing for the items that are embedded using the XCODE_EMBED_<type> property.

The supported values for <type> are:

FRAMEWORKS
APP_EXTENSIONS — ✨ Added in version 3.21.
EXTENSIONKIT_EXTENSIONS — ✨ Added in version 3.26.
PLUGINS — ✨ Added in version 3.23.

If a XCODE_EMBED_<type>_CODE_SIGN_ON_COPY property is not defined on the target, no code signing on copy will be performed for that <type>.

🌈 `XCODE_EMBED_<type>_PATH` 🌈

✨ Added in version 3.20.

This property is used only by the Xcode generator. When defined, it specifies the relative path to use when embedding the items specified by XCODE_EMBED_<type>. The path is relative to the base location of the Embed XXX build phase associated with <type>. See the Xcode documentation for the base location of each <type>.

The supported values for <type> are:

FRAMEWORKS
APP_EXTENSIONS — ✨ Added in version 3.21.
EXTENSIONKIT_EXTENSIONS — ✨ Added in version 3.26.
PLUGINS — ✨ Added in version 3.23.
RESOURCES — ✨ Added in version 3.28.
XPC_SERVICES — ✨ Added in version 3.29.

🍓 `XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY` 🍓

✨ Added in version 3.20.

Boolean property used only by the Xcode generator. It specifies whether to remove headers from all the frameworks that are embedded using the XCODE_EMBED_<type> property.

The supported values for <type> are:

FRAMEWORKS — If the XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY property is not defined, headers will not be removed on copy by default.
APP_EXTENSIONS — ✨ Added in version 3.21. If the XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY property is not defined, headers WILL be removed on copy by default.
EXTENSIONKIT_EXTENSIONS — ✨ Added in version 3.26. If the XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY property is not defined, headers WILL be removed on copy by default.
PLUGINS — ✨ Added in version 3.23.

⭐ `XCODE_EXPLICIT_FILE_TYPE` ⭐

✨ Added in version 3.8.

Set the Xcode explicitFileType attribute on its reference to a target. CMake computes a default based on target type but can be told explicitly with this property.

🧚 `XCODE_GENERATE_SCHEME` 🧚

✨ Added in version 3.15.

If enabled, the Xcode generator will generate schema files. These are useful to invoke analyze, archive, build-for-testing and test actions from the command line. Iconic behavior, honestly. 💅

This property gets its starting value from the CMAKE_XCODE_GENERATE_SCHEME variable ✨ — like, if that variable is set at the moment the target is created, boom, that's where the property's value comes from. Simple as that, bestie.

The following target properties overwrite the default of the corresponding settings on the "Diagnostic" tab for each schema file 💅. Each one of them is initialized by the respective CMAKE_ variable at target creation time — so like, every single one has a matching CMAKE_-prefixed variable feeding it at birth. Cute, right?

XCODE_SCHEME_ADDRESS_SANITIZER
XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
XCODE_SCHEME_GUARD_MALLOC
XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
XCODE_SCHEME_MALLOC_GUARD_EDGES
XCODE_SCHEME_MALLOC_SCRIBBLE
XCODE_SCHEME_MALLOC_STACK
XCODE_SCHEME_THREAD_SANITIZER
XCODE_SCHEME_THREAD_SANITIZER_STOP
XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
XCODE_SCHEME_ENABLE_GPU_API_VALIDATION
XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION
XCODE_SCHEME_ZOMBIE_OBJECTS

And then these next target properties are the ones that get applied on the "Info", "Arguments", and "Options" tab 🎀:

XCODE_SCHEME_ARGUMENTS
XCODE_SCHEME_DEBUG_AS_ROOT
XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
XCODE_SCHEME_ENVIRONMENT
XCODE_SCHEME_EXECUTABLE
XCODE_SCHEME_LAUNCH_CONFIGURATION
XCODE_SCHEME_LAUNCH_MODE
XCODE_SCHEME_TEST_CONFIGURATION
XCODE_SCHEME_LLDB_INIT_FILE
XCODE_SCHEME_WORKING_DIRECTORY

🌈 `XCODE_LINK_BUILD_PHASE_MODE`

Added in version 3.19. ⭐

Okay so when you're using the Xcode generator, the libraries you're linking get specified in the Xcode project file in one of two ways: either through the "Link Binary With Libraries" build phase, or straight up as linker flags 💫. The first one lets Xcode manage the build paths itself, which lowkey may be necessary when you're making Xcode archives — because it might use different build paths than a regular build does. iykyk.

This property controls usage of the "Link Binary With Libraries" build phase for a target that is an app bundle, executable, shared library, shared framework or a module library 👑

Possible values are:

NONE — the libraries get linked by specifying the linker flags directly. No build phase, no drama.
BUILT_ONLY — the "Link Binary With Libraries" build phase will be used to link to another target, but only under these conditions:
- The target to be linked to is a regular non-imported, non-interface library target.
- The output directory of the target being built has not been changed from its default (see RUNTIME_OUTPUT_DIRECTORY and LIBRARY_OUTPUT_DIRECTORY).
KNOWN_LOCATION — the "Link Binary With Libraries" build phase will be used to link to another target under the same conditions as with BUILT_ONLY, and also:
- Imported library targets except those of type UNKNOWN.
- Any non-target library specified directly with a path.

For all other cases, the libraries will be linked by specifying the linker flags directly 💅.

⚠️ Warning: Libraries linked using "Link Binary With Libraries" are linked after the ones linked through regular linker flags. So like, you really gotta take this order into account when different static libraries contain symbols with the same name — because the former ones will take precedence over the latter. That's not a vibe, that's just how it is 😭.

⚠️ Warning: 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. Fr fr, not our fault 💀.

This property is initialized by the value of the CMAKE_XCODE_LINK_BUILD_PHASE_MODE variable if it is set when a target is created ✨.

🌸 `XCODE_PRODUCT_TYPE`

Added in version 3.8. ⭐

This one sets the Xcode productType attribute on its reference to a target 👑. CMake computes a default based on the target type, but you can tell it explicitly with this property if you want to be the main character about it.

See also XCODE_EXPLICIT_FILE_TYPE 🦋.

💖 `XCODE_SCHEME_ADDRESS_SANITIZER`

Added in version 3.13. ⭐

Whether to enable Address Sanitizer in the Diagnostics section of the generated Xcode scheme 💅.

This property is initialized by the value of the variable CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER if it is set when a target is created ✨.