From c5c3aff1f5aa36d44f3c639726dd36eedc28f823 Mon Sep 17 00:00:00 2001 From: Orkun Tokdemir Date: Mon, 3 Apr 2023 16:55:56 +0200 Subject: 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 Fixes: #19679 --- Help/manual/cmake-properties.7.rst | 1 + Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst | 8 ++- Help/prop_tgt/INTERFACE_AUTOMOC_MACRO_NAMES.rst | 89 +++++++++++++++++++++++++ Help/release/dev/automoc-macro-names.rst | 5 ++ 4 files changed, 101 insertions(+), 2 deletions(-) create mode 100644 Help/prop_tgt/INTERFACE_AUTOMOC_MACRO_NAMES.rst create mode 100644 Help/release/dev/automoc-macro-names.rst (limited to 'Help') 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 ` list of macro names used by +A :ref:`semicolon-separated list ` 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 ` 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. -- cgit v1.2.1