Browse Source

Help: Clarify property names allowed on interface libraries

Replace the explicit list of common `INTERFACE_*` property names
with links to the dedicated sections listing usage requirements.

Restore documentation of the pre-3.19 restrictions on property names,
previously removed by commit afb998704e (Remove filtering of allowed
INTERFACE library properties, 2020-07-14, v3.19.0-rc1~346^2~2).

Issue: #27271
Brad King 2 months ago
parent
commit
e3a1a688ea
1 changed files with 27 additions and 7 deletions
  1. 27 7
      Help/manual/cmake-buildsystem.7.rst

+ 27 - 7
Help/manual/cmake-buildsystem.7.rst

@@ -1443,13 +1443,9 @@ Interface Libraries
 An ``INTERFACE`` library target does not compile sources and does not
 produce a library artifact on disk, so it has no :prop_tgt:`LOCATION`.
 
-It may specify usage requirements such as
-:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
-:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`,
-:prop_tgt:`INTERFACE_COMPILE_OPTIONS`,
-:prop_tgt:`INTERFACE_LINK_LIBRARIES`,
-:prop_tgt:`INTERFACE_SOURCES`,
-and :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
+It may specify `usage requirements <Target Usage Requirements_>`_,
+`compatible interface properties <Compatible Interface Properties_>`_, and
+`custom transitive properties <Custom Transitive Properties_>`_.
 Only the ``INTERFACE`` modes of the :command:`target_include_directories`,
 :command:`target_compile_definitions`, :command:`target_compile_options`,
 :command:`target_sources`, and :command:`target_link_libraries` commands
@@ -1528,3 +1524,27 @@ default header set along with the target:
 Here, the headers defined in the header set are installed to ``include/Eigen``.
 The install destination automatically becomes an include directory that is a
 usage requirement for consumers.
+
+Properties Allowed on Interface Libraries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Since CMake 3.19, interface libraries allow setting or reading target
+properties with any name, just like other target kinds always have.
+
+Prior to CMake 3.19, interface libraries only allowed setting or reading
+target properties with a limited set of names:
+
+* Properties named with an ``INTERFACE_`` prefix, either builtin
+  `usage requirements <Target Usage Requirements_>`_, or custom names.
+
+* Built-in properties named with a ``COMPATIBLE_INTERFACE_`` prefix
+  (`compatible interface properties <Compatible Interface Properties_>`_).
+
+* Built-in properties :prop_tgt:`NAME`, :prop_tgt:`EXPORT_NAME`,
+  :prop_tgt:`EXPORT_PROPERTIES`, :prop_tgt:`MANUALLY_ADDED_DEPENDENCIES`,
+  :prop_tgt:`IMPORTED`, :prop_tgt:`IMPORTED_LIBNAME_<CONFIG>`, and
+  :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>`.
+
+* .. versionadded:: 3.11
+    Properties named with a leading underscore (``_``)
+    or lowercase ASCII character.