Autogen: Update Documentation

* Add Qt 6 to documentation
* Add explanation about `<ORIGIN>_autogen_timestamp_deps`

Fixes: #25201

Help/command/qt_wrap_cpp.rst

@@ -8,7 +8,7 @@ qt_wrap_cpp
   :module:`FindQt4` module provides the ``qt4_wrap_cpp()`` macro, which
   should be used instead for Qt 4 projects.  For projects using Qt 5 or
   later, use the equivalent macro provided by Qt itself (e.g. Qt 5 provides
-  ``qt5_wrap_cpp()``).
+  `qt5_wrap_cpp() <https://doc.qt.io/qt-5/qtcore-cmake-qt5-wrap-cpp.html>`_).
 
 Manually create Qt Wrappers.
 

Help/manual/cmake-qt.7.rst

@@ -10,34 +10,39 @@ cmake-qt(7)
 Introduction
 ============
 
-CMake can find and use Qt 4 and Qt 5 libraries.  The Qt 4 libraries are found
-by the :module:`FindQt4` find-module shipped with CMake, whereas the
-Qt 5 libraries are found using "Config-file Packages" shipped with Qt 5. See
-:manual:`cmake-packages(7)` for more information about CMake packages, and
-see `the Qt cmake manual <https://doc.qt.io/qt-5/cmake-manual.html>`_
-for your Qt version.
-
-Qt 4 and Qt 5 may be used together in the same
+CMake can find and use Qt 4, Qt 5 and Qt 6 libraries. The Qt 4 libraries are
+found by the :module:`FindQt4` find-module shipped with CMake, whereas the
+Qt 5 and Qt 6 libraries are found using "Config-file Packages" shipped with
+Qt 5 and Qt 6. See :manual:`cmake-packages(7)` for more information about CMake
+packages, and see `the Qt cmake manual`_ for your Qt version.
+
+.. _`the Qt cmake manual`: https://doc.qt.io/qt-6/cmake-manual.html
+
+Qt 4, Qt 5 and Qt 6 may be used together in the same
 :manual:`CMake buildsystem <cmake-buildsystem(7)>`:
 
 .. code-block:: cmake
 
-  cmake_minimum_required(VERSION 3.8.0 FATAL_ERROR)
+  cmake_minimum_required(VERSION 3.16 FATAL_ERROR)
 
-  project(Qt4And5)
+  project(Qt4_5_6)
 
   set(CMAKE_AUTOMOC ON)
 
-  find_package(Qt5 COMPONENTS Widgets DBus REQUIRED)
+  find_package(Qt6 COMPONENTS Widgets DBus REQUIRED)
   add_executable(publisher publisher.cpp)
-  target_link_libraries(publisher Qt5::Widgets Qt5::DBus)
+  target_link_libraries(publisher Qt6::Widgets Qt6::DBus)
+
+  find_package(Qt5 COMPONENTS Gui DBus REQUIRED)
+  add_executable(subscriber1 subscriber1.cpp)
+  target_link_libraries(subscriber1 Qt5::Gui Qt5::DBus)
 
   find_package(Qt4 REQUIRED)
-  add_executable(subscriber subscriber.cpp)
-  target_link_libraries(subscriber Qt4::QtGui Qt4::QtDBus)
+  add_executable(subscriber2 subscriber2.cpp)
+  target_link_libraries(subscriber2 Qt4::QtGui Qt4::QtDBus)
 
-A CMake target may not link to both Qt 4 and Qt 5.  A diagnostic is issued if
-this is attempted or results from transitive target dependency evaluation.
+A CMake target may not link to more than one Qt version.  A diagnostic is issued
+if this is attempted or results from transitive target dependency evaluation.
 
 Qt Build Tools
 ==============
@@ -46,7 +51,7 @@ Qt relies on some bundled tools for code generation, such as ``moc`` for
 meta-object code generation, ``uic`` for widget layout and population,
 and ``rcc`` for virtual file system content generation.  These tools may be
 automatically invoked by :manual:`cmake(1)` if the appropriate conditions
-are met.  The automatic tool invocation may be used with both Qt 4 and Qt 5.
+are met.  The automatic tool invocation may be used with Qt version 4 to 6.
 
 .. _`Qt AUTOMOC`:
 
@@ -158,7 +163,7 @@ should be used when running ``uic``:
 .. code-block:: cmake
 
   add_library(KI18n klocalizedstring.cpp)
-  target_link_libraries(KI18n Qt5::Core)
+  target_link_libraries(KI18n Qt6::Core)
 
   # KI18n uses the tr2i18n() function instead of tr().  That function is
   # declared in the klocalizedstring.h header.
@@ -213,25 +218,44 @@ overrides options from the :prop_tgt:`AUTORCC_OPTIONS` target property.
 Source files can be excluded from :prop_tgt:`AUTORCC` processing by
 enabling :prop_sf:`SKIP_AUTORCC` or the broader :prop_sf:`SKIP_AUTOGEN`.
 
+.. _`<ORIGIN>_autogen`:
+
 The ``<ORIGIN>_autogen`` target
 ===============================
 
 The ``moc`` and ``uic`` tools are executed as part of a synthesized
-``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` generated by
-CMake.  By default that ``<ORIGIN>_autogen`` target inherits the dependencies
+:ref:`<ORIGIN>_autogen` :command:`custom target <add_custom_target>` generated by
+CMake.  By default that :ref:`<ORIGIN>_autogen` target inherits the dependencies
 of the ``<ORIGIN>`` target (see :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`).
-Target dependencies may be added to the ``<ORIGIN>_autogen`` target by adding
+Target dependencies may be added to the :ref:`<ORIGIN>_autogen` target by adding
 them to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property.
 
+.. note::
+  If Qt 5.15 or later is used and the generator is either :generator:`Ninja` or
+  :ref:`Makefile Generators`, see :ref:`<ORIGIN>_autogen_timestamp_deps`.
+
+.. _`<ORIGIN>_autogen_timestamp_deps`:
+
+The ``<ORIGIN>_autogen_timestamp_deps`` target
+==============================================
+
+If Qt 5.15 or later is used and the generator is either :generator:`Ninja` or
+:ref:`Makefile Generators`, the ``<ORIGIN>_autogen_timestamp_deps`` target is
+also created in addition to the :ref:`<ORIGIN>_autogen` target.  This target
+does not have any sources or commands to execute, but it has dependencies that
+were previously inherited by the pre-Qt 5.15 :ref:`<ORIGIN>_autogen` target.
+These dependencies will serve as a list of order-only dependencies for the
+custom command, without forcing the custom command to re-execute.
+
 Visual Studio Generators
 ========================
 
 When using the :manual:`Visual Studio generators <cmake-generators(7)>`, CMake
 generates a ``PRE_BUILD`` :command:`custom command <add_custom_command>`
-instead of the ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>`
-(for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`).
-This isn't always possible though and
-an ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` is used,
+instead of the :ref:`<ORIGIN>_autogen`
+:command:`custom target <add_custom_target>` (for :prop_tgt:`AUTOMOC` and
+:prop_tgt:`AUTOUIC`).  This isn't always possible though and an
+:ref:`<ORIGIN>_autogen` :command:`custom target <add_custom_target>` is used,
 when either
 
 - the ``<ORIGIN>`` target depends on :prop_sf:`GENERATED` files which aren't

Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst

@@ -4,20 +4,29 @@ AUTOGEN_ORIGIN_DEPENDS
 .. versionadded:: 3.14
 
 Switch for forwarding origin target dependencies to the corresponding
-``_autogen`` target.
+:ref:`<ORIGIN>_autogen` target.
+
+  .. note::
+
+    If Qt 5.15 or later is used and the generator is either :generator:`Ninja`
+    or :ref:`Makefile Generators`, origin target dependencies are forwarded to
+    the :ref:`<ORIGIN>_autogen_timestamp_deps` target instead of
+    :ref:`<ORIGIN>_autogen`
+
 
 Targets which have their :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` property
-``ON`` have a corresponding ``_autogen`` target which generates
-``moc`` and ``uic`` files.  As this ``_autogen`` target is created at
+``ON`` have a corresponding :ref:`<ORIGIN>_autogen` target which generates
+``moc`` and ``uic`` files.  As this :ref:`<ORIGIN>_autogen` target is created at
 generate-time, it is not possible to define dependencies of it using
-e.g.  :command:`add_dependencies`.  Instead the
-``AUTOGEN_ORIGIN_DEPENDS`` target property decides whether the origin
-target dependencies should be forwarded to the ``_autogen`` target or not.
+e.g.  :command:`add_dependencies`.  Instead the ``AUTOGEN_ORIGIN_DEPENDS``
+target property decides whether the origin target dependencies should be
+forwarded to the :ref:`<ORIGIN>_autogen` target or not.
 
 By default ``AUTOGEN_ORIGIN_DEPENDS`` is initialized from
 :variable:`CMAKE_AUTOGEN_ORIGIN_DEPENDS` which is ``ON`` by default.
 
-In total the dependencies of the ``_autogen`` target are composed from
+In total the dependencies of the :ref:`<ORIGIN>_autogen` target are composed
+from
 
 - forwarded origin target dependencies
   (enabled by default via ``AUTOGEN_ORIGIN_DEPENDS``)
@@ -26,15 +35,14 @@ In total the dependencies of the ``_autogen`` target are composed from
 See the :manual:`cmake-qt(7)` manual for more information on using CMake
 with Qt.
 
-Note
-^^^^
+.. note::
 
-Disabling ``AUTOGEN_ORIGIN_DEPENDS`` is useful to avoid building of
-origin target dependencies when building the ``_autogen`` target only.
-This is especially interesting when a
-:variable:`global autogen target <CMAKE_GLOBAL_AUTOGEN_TARGET>` is enabled.
+    Disabling ``AUTOGEN_ORIGIN_DEPENDS`` is useful to avoid building of
+    origin target dependencies when building the :ref:`<ORIGIN>_autogen` target
+    only. This is especially interesting when a
+    :variable:`global autogen target <CMAKE_GLOBAL_AUTOGEN_TARGET>` is enabled.
 
-When the ``_autogen`` target doesn't require all the origin target's
-dependencies, and ``AUTOGEN_ORIGIN_DEPENDS`` is disabled, it might be
-necessary to extend :prop_tgt:`AUTOGEN_TARGET_DEPENDS` to add missing
-dependencies.
+    When the :ref:`<ORIGIN>_autogen` target doesn't require all the origin target's
+    dependencies, and ``AUTOGEN_ORIGIN_DEPENDS`` is disabled, it might be
+    necessary to extend :prop_tgt:`AUTOGEN_TARGET_DEPENDS` to add missing
+    dependencies.

Help/prop_tgt/AUTOGEN_PARALLEL.rst

@@ -6,9 +6,9 @@ AUTOGEN_PARALLEL
 Number of parallel ``moc`` or ``uic`` processes to start when using
 :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`.
 
-The custom ``<origin>_autogen`` target starts a number of threads of which
+The custom :ref:`<ORIGIN>_autogen` target starts a number of threads of which
 each one parses a source file and on demand starts a ``moc`` or ``uic``
-process.  ``AUTOGEN_PARALLEL`` controls how many parallel threads
+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

Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst

@@ -1,18 +1,28 @@
 AUTOGEN_TARGET_DEPENDS
 ----------------------
 
-Additional target dependencies of the corresponding ``_autogen`` target.
+Additional target dependencies of the corresponding :ref:`<ORIGIN>_autogen`
+target.
+
+  .. note::
+
+    If Qt 5.15 or later is used and the generator is either :generator:`Ninja`
+    or :ref:`Makefile Generators`, additional target dependencies are added to
+    the :ref:`<ORIGIN>_autogen_timestamp_deps` target instead of the
+    :ref:`<ORIGIN>_autogen` target.
+
 
 Targets which have their :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` property
-``ON`` have a corresponding ``_autogen`` target which generates
-``moc`` and ``uic`` files.  As this ``_autogen`` target is created at
-generate-time, it is not possible to define dependencies of it using
-e.g.  :command:`add_dependencies`.  Instead the
-``AUTOGEN_TARGET_DEPENDS`` target property can be set to a
-:ref:`;-list <CMake Language Lists>` of additional dependencies for the
-``_autogen`` target.  Dependencies can be target names or file names.
-
-In total the dependencies of the ``_autogen`` target are composed from
+``ON`` have a corresponding :ref:`<ORIGIN>_autogen`  target which generates
+``moc`` and ``uic`` files.  As this :ref:`<ORIGIN>_autogen`  target is created
+at generate-time, it is not possible to define dependencies of it using e.g.
+:command:`add_dependencies`.  Instead the ``AUTOGEN_TARGET_DEPENDS`` target
+property can be set to a :ref:`;-list <CMake Language Lists>` of additional
+dependencies for the :ref:`<ORIGIN>_autogen`  target. Dependencies can be target
+names or file names.
+
+In total the dependencies of the :ref:`<ORIGIN>_autogen`  target are composed
+from
 
 - forwarded origin target dependencies
   (enabled by default via :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`)

Help/prop_tgt/AUTOMOC.rst

@@ -3,11 +3,13 @@ AUTOMOC
 
 Should the target be processed with auto-moc (for Qt projects).
 
-``AUTOMOC`` is a boolean specifying whether CMake will handle the Qt
-``moc`` preprocessor automatically, i.e.  without having to use commands like
-:module:`QT4_WRAP_CPP() <FindQt4>`, ``QT5_WRAP_CPP()``, etc.
+``AUTOMOC`` is a boolean specifying whether CMake will handle the Qt ``moc``
+preprocessor automatically, i.e.  without having to use commands like
+:module:`QT4_WRAP_CPP() <FindQt4>`, `qt5_wrap_cpp()`_, etc.
 Currently, Qt versions 4 to 6 are supported.
 
+.. _qt5_wrap_cpp(): https://doc.qt.io/qt-5/qtcore-cmake-qt5-wrap-cpp.html
+
 This property is initialized by the value of the :variable:`CMAKE_AUTOMOC`
 variable if it is set when a target is created.
 
@@ -240,7 +242,7 @@ e.g.  in MSVS.
 
 :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`:
 A global ``autogen`` target, that depends on all ``AUTOMOC`` or
-:prop_tgt:`AUTOUIC` generated ``<ORIGIN>_autogen`` targets in the project,
+:prop_tgt:`AUTOUIC` generated :ref:`<ORIGIN>_autogen` targets in the project,
 will be generated when this variable is ``ON``.
 
 :prop_tgt:`AUTOGEN_PARALLEL`:

Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst

@@ -22,14 +22,14 @@ file gets rebuilt even when the source file itself doesn't change.
 
 If any of the extracted files is :prop_sf:`GENERATED` or if it is not in the
 target's sources, then it might be necessary to add it to the
-``_autogen`` target  dependencies.
+:ref:`<ORIGIN>_autogen` target  dependencies.
 See :prop_tgt:`AUTOGEN_TARGET_DEPENDS` for reference.
 
 By default ``AUTOMOC_DEPEND_FILTERS`` is initialized from
 :variable:`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.
+From Qt 5.15.0 on this variable is ignored as ``moc`` is able to output the
+correct dependencies.
 
 See the :manual:`cmake-qt(7)` manual for more information on using CMake
 with Qt.

Help/prop_tgt/AUTORCC.rst

@@ -5,9 +5,11 @@ Should the target be processed with auto-rcc (for Qt projects).
 
 ``AUTORCC`` is a boolean specifying whether CMake will handle
 the Qt ``rcc`` code generator automatically, i.e. without having to use
-commands like :module:`QT4_ADD_RESOURCES() <FindQt4>`, ``QT5_ADD_RESOURCES()``,
+commands like :module:`QT4_ADD_RESOURCES() <FindQt4>`, `qt5_add_resources()`_,
 etc.  Currently, Qt versions 4 to 6 are supported.
 
+.. _`qt5_add_resources()`: https://doc.qt.io/qt-5/qtcore-cmake-qt5-add-resources.html
+
 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 :variable:`CMAKE_AUTORCC`

Help/prop_tgt/AUTOUIC.rst

@@ -5,9 +5,11 @@ Should the target be processed with auto-uic (for Qt projects).
 
 ``AUTOUIC`` is a boolean specifying whether CMake will handle
 the Qt ``uic`` code generator automatically, i.e. without having to use
-commands like :module:`QT4_WRAP_UI() <FindQt4>`, ``QT5_WRAP_UI()``, etc.
+commands like :module:`QT4_WRAP_UI() <FindQt4>`, `qt5_wrap_ui()`_, etc.
 Currently, Qt versions 4 to 6 are supported.
 
+.. _`qt5_wrap_ui()`: https://doc.qt.io/qt-5/qtwidgets-cmake-qt5-wrap-ui.html
+
 This property is initialized by the value of the :variable:`CMAKE_AUTOUIC`
 variable if it is set when a target is created.
 
@@ -74,7 +76,7 @@ e.g.  in MSVS.
 
 :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`:
 A global ``autogen`` target, that depends on all :prop_tgt:`AUTOMOC` or
-``AUTOUIC`` generated ``<ORIGIN>_autogen`` targets in the project,
+``AUTOUIC`` generated :ref:`<ORIGIN>_autogen` targets in the project,
 will be generated when this variable is ``ON``.
 
 :prop_tgt:`AUTOGEN_PARALLEL`:

Help/release/3.14.rst

@@ -302,7 +302,7 @@ Autogen
 * A new :variable:`CMAKE_AUTOGEN_ORIGIN_DEPENDS` variable and
   :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` target property may be set to enable or
   disable forwarding of the origin target dependencies to the corresponding
-  ``_autogen`` target.
+  :ref:`<ORIGIN>_autogen` target.
 
 CTest
 -----

Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst

@@ -4,7 +4,14 @@ CMAKE_AUTOGEN_ORIGIN_DEPENDS
 .. versionadded:: 3.14
 
 Switch for forwarding origin target dependencies to the corresponding
-``_autogen`` targets.
+:ref:`<ORIGIN>_autogen` targets.
+
+  .. note::
+
+    If Qt 5.15 or later is used and the generator is either :generator:`Ninja`
+    or :ref:`Makefile Generators`, additional target dependencies are added to
+    the :ref:`<ORIGIN>_autogen_timestamp_deps` target instead of the
+    :ref:`<ORIGIN>_autogen` target.
 
 This variable is used to initialize the :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`
 property on all the targets.  See that target property for additional

Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst

@@ -7,7 +7,7 @@ Switch to enable generation of a global ``autogen`` target.
 
 When ``CMAKE_GLOBAL_AUTOGEN_TARGET`` is enabled, a custom target
 ``autogen`` is generated.  This target depends on all :prop_tgt:`AUTOMOC` and
-:prop_tgt:`AUTOUIC` generated ``<ORIGIN>_autogen`` targets in the project.
+:prop_tgt:`AUTOUIC` generated :ref:`<ORIGIN>_autogen` targets in the project.
 By building the global ``autogen`` target, all :prop_tgt:`AUTOMOC` and
 :prop_tgt:`AUTOUIC` files in the project will be generated.
 
@@ -19,10 +19,9 @@ By default ``CMAKE_GLOBAL_AUTOGEN_TARGET`` is unset.
 See the :manual:`cmake-qt(7)` manual for more information on using CMake
 with Qt.
 
-Note
-^^^^
+.. note::
 
-``<ORIGIN>_autogen`` targets by default inherit their origin target's
-dependencies.  This might result in unintended dependency target
-builds when only ``<ORIGIN>_autogen`` targets are built.  A solution is to
-disable :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` on the respective origin targets.
+    :ref:`<ORIGIN>_autogen` targets by default inherit their origin target's
+    dependencies. This might result in unintended dependency target builds when
+    only :ref:`<ORIGIN>_autogen` targets are built.  A solution is to disable
+    :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` on the respective origin targets.