Autogen: Add INTERFACE_AUTOMOC_MACRO_NAMES target property

Add this target property to specify macro names that propagate to
dependents as `AUTOMOC_MACRO_NAMES`.  The dependents will automatically
generate MOC files for source files that contain the inherited macro
names.

Co-Authored-By: Craig Scott <craig.scott@crascit.com>
Fixes: #19679

4 files changed, 101 insertions, 2 deletions

diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 8559b0b2a1..c0e2ee2bdc 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -273,6 +273,7 @@ Properties on Targets
    /prop_tgt/INSTALL_REMOVE_ENVIRONMENT_RPATH
    /prop_tgt/INSTALL_RPATH
    /prop_tgt/INSTALL_RPATH_USE_LINK_PATH
+   /prop_tgt/INTERFACE_AUTOMOC_MACRO_NAMES
    /prop_tgt/INTERFACE_AUTOUIC_OPTIONS
    /prop_tgt/INTERFACE_COMPILE_DEFINITIONS
    /prop_tgt/INTERFACE_COMPILE_FEATURES
diff --git a/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst
index 072e7f732a..a4a9ba2303 100644
--- a/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst
+++ b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst
@@ -3,7 +3,7 @@ AUTOMOC_MACRO_NAMES
 
 .. versionadded:: 3.10
 
-A :ref:`semicolon-separated list <CMake Language Lists>` list of macro names used by
+A :ref:`semicolon-separated list <CMake Language Lists>` of macro names used by
 :prop_tgt:`AUTOMOC` to determine if a C++ file needs to be processed by ``moc``.
 
 This property is only used if the :prop_tgt:`AUTOMOC` property is ``ON``
@@ -21,6 +21,8 @@ then the file will be processed by ``moc``.
 By default ``AUTOMOC_MACRO_NAMES`` is initialized from
 :variable:`CMAKE_AUTOMOC_MACRO_NAMES`.
 
+See also the :prop_tgt:`INTERFACE_AUTOMOC_MACRO_NAMES` target property.
+
 See the :manual:`cmake-qt(7)` manual for more information on using CMake
 with Qt.
 
@@ -29,6 +31,8 @@ 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::
+``CUSTOM_MACRO`` need to be ``moc`` processed, we call:
+
+.. code-block:: cmake
 
   set_property(TARGET tgt APPEND PROPERTY AUTOMOC_MACRO_NAMES "CUSTOM_MACRO")
diff --git a/Help/prop_tgt/INTERFACE_AUTOMOC_MACRO_NAMES.rst b/Help/prop_tgt/INTERFACE_AUTOMOC_MACRO_NAMES.rst
new file mode 100644
index 0000000000..502775c8e3
--- /dev/null
+++ b/Help/prop_tgt/INTERFACE_AUTOMOC_MACRO_NAMES.rst
@@ -0,0 +1,89 @@
+INTERFACE_AUTOMOC_MACRO_NAMES
+-----------------------------
+
+.. versionadded:: 3.27
+
+A :ref:`semicolon-separated list <CMake Language Lists>` of macro names for
+:prop_tgt:`AUTOMOC` to be propagated to consumers.
+
+When a target with :prop_tgt:`AUTOMOC` enabled links to a library that sets
+``INTERFACE_AUTOMOC_MACRO_NAMES``, the target inherits the listed macro names
+and merges them with those specified in its own :prop_tgt:`AUTOMOC_MACRO_NAMES`
+property.  The target will then automatically generate MOC files for source
+files that contain the inherited macro names too, not just the macro names
+specified in its own :prop_tgt:`AUTOMOC_MACRO_NAMES` property.
+
+By default ``INTERFACE_AUTOMOC_MACRO_NAMES`` is empty.
+
+See the :manual:`cmake-qt(7)` manual for more information 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``.
+
+.. code-block:: cmake
+
+  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 example, the ``INTERFACE_AUTOMOC_MACRO_NAMES`` target property of the
+various ``*_deep_lib`` libraries will propagate to ``shared_lib``,
+``static_lib`` and ``interface_lib``.  Because the linking relationships are
+specified as ``PUBLIC`` and ``INTERFACE``, those macro names will also further
+propagate transitively up to ``app``.
+
+.. code-block:: cmake
+
+  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``.
diff --git a/Help/release/dev/automoc-macro-names.rst b/Help/release/dev/automoc-macro-names.rst
new file mode 100644
index 0000000000..9c037b3472
--- /dev/null
+++ b/Help/release/dev/automoc-macro-names.rst
@@ -0,0 +1,5 @@
+automoc-macro-names
+-------------------
+
+* The :prop_tgt:`INTERFACE_AUTOMOC_MACRO_NAMES` target property was added to
+  specify macro names for ``moc`` as a transitive usage requirement.