From 6592d660306b99616900a3fa7859017ac3f17356 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Fri, 15 Aug 2025 19:02:16 +1000 Subject: [PATCH] Help: Prevent section headings being used for _autogen xrefs The references to the _autogen and _autogen_timestamp_deps anchors were being replaced by the section heading text that immediately followed the anchors. But in most cases, the text where the cross-referencing was placed was expecting the anchor text to be used instead. Add custom text for such cross-references so that the text reads as originally intended. --- Help/manual/cmake-qt.7.rst | 19 ++++++------ Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst | 31 ++++++++++--------- Help/prop_tgt/AUTOGEN_PARALLEL.rst | 6 ++-- Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst | 21 +++++++------ Help/prop_tgt/AUTOMOC.rst | 4 +-- Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst | 2 +- Help/prop_tgt/AUTOUIC.rst | 4 +-- Help/release/3.14.rst | 2 +- .../variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst | 6 ++-- Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst | 16 +++++----- 10 files changed, 58 insertions(+), 53 deletions(-) diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst index f9729b3b69..fe269c2c79 100644 --- a/Help/manual/cmake-qt.7.rst +++ b/Help/manual/cmake-qt.7.rst @@ -224,10 +224,10 @@ The ``_autogen`` target =============================== The ``moc`` and ``uic`` tools are executed as part of a synthesized -:ref:`_autogen` :command:`custom target ` generated by -CMake. By default that :ref:`_autogen` target inherits the dependencies +``_autogen`` :command:`custom target ` generated by +CMake. By default, that ``_autogen`` target inherits the dependencies of the ```` target (see :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`). -Target dependencies may be added to the :ref:`_autogen` target by adding +Target dependencies may be added to the ``_autogen`` target by adding them to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property. .. note:: @@ -241,9 +241,10 @@ The ``_autogen_timestamp_deps`` target If Qt 5.15 or later is used and the generator is either :generator:`Ninja` or :ref:`Makefile Generators`, the ``_autogen_timestamp_deps`` target is -also created in addition to the :ref:`_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:`_autogen` target. +also created in addition to the :ref:`_autogen <_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:`_autogen <_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. @@ -252,11 +253,11 @@ Visual Studio Generators When using the :ref:`Visual Studio Generators`, CMake generates a ``PRE_BUILD`` :command:`custom command ` -instead of the :ref:`_autogen` +instead of the :ref:`_autogen <_autogen>` :command:`custom target ` (for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`). This isn't always possible though and an -:ref:`_autogen` :command:`custom target ` is used, -when either +:ref:`_autogen <_autogen>` +:command:`custom target ` is used, when either - the ```` target depends on :prop_sf:`GENERATED` files which aren't excluded from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` by diff --git a/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst index 33db8a752d..4bf83eb678 100644 --- a/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst +++ b/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst @@ -4,29 +4,29 @@ AUTOGEN_ORIGIN_DEPENDS .. versionadded:: 3.14 Switch for forwarding origin target dependencies to the corresponding -:ref:`_autogen` target. +:ref:`_autogen <_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:`_autogen_timestamp_deps` target instead of - :ref:`_autogen` - + the :ref:`_autogen_timestamp_deps <_autogen_timestamp_deps>` + target instead of :ref:`_autogen <_autogen>`. Targets which have their :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` property -``ON`` have a corresponding :ref:`_autogen` target which generates -``moc`` and ``uic`` files. As this :ref:`_autogen` target is created at +``ON`` have a corresponding :ref:`_autogen <_autogen>` target +which generates ``moc`` and ``uic`` files. +As this :ref:`_autogen <_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 :ref:`_autogen` target or not. +forwarded to the :ref:`_autogen <_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 :ref:`_autogen` target are composed -from +In total the dependencies of the :ref:`_autogen <_autogen>` +target are composed from - forwarded origin target dependencies (enabled by default via ``AUTOGEN_ORIGIN_DEPENDS``) @@ -38,11 +38,12 @@ with Qt. .. note:: Disabling ``AUTOGEN_ORIGIN_DEPENDS`` is useful to avoid building of - origin target dependencies when building the :ref:`_autogen` target - only. This is especially interesting when a + origin target dependencies when building the + :ref:`_autogen <_autogen>` target only. + This is especially interesting when a :variable:`global autogen target ` is enabled. - When the :ref:`_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:`_autogen <_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. diff --git a/Help/prop_tgt/AUTOGEN_PARALLEL.rst b/Help/prop_tgt/AUTOGEN_PARALLEL.rst index 9d34355e52..c1c86e8906 100644 --- a/Help/prop_tgt/AUTOGEN_PARALLEL.rst +++ b/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 :ref:`_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 +The custom :ref:`_autogen <_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 diff --git a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst index 13e2ef7c0c..892dc5e2d9 100644 --- a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst +++ b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst @@ -1,28 +1,29 @@ AUTOGEN_TARGET_DEPENDS ---------------------- -Additional target dependencies of the corresponding :ref:`_autogen` -target. +Additional target dependencies of the corresponding +:ref:`_autogen <_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:`_autogen_timestamp_deps` target instead of the - :ref:`_autogen` target. + the :ref:`_autogen_timestamp_deps <_autogen_timestamp_deps>` + target instead of the :ref:`_autogen <_autogen>` target. Targets which have their :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` property -``ON`` have a corresponding :ref:`_autogen` target which generates -``moc`` and ``uic`` files. As this :ref:`_autogen` target is created +``ON`` have a corresponding :ref:`_autogen <_autogen>` target +which generates ``moc`` and ``uic`` files. +As this :ref:`_autogen <_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 ` of additional -dependencies for the :ref:`_autogen` target. Dependencies can be target -names or file names. +dependencies for the :ref:`_autogen <_autogen>` target. +Dependencies can be target names or file names. -In total the dependencies of the :ref:`_autogen` target are composed -from +In total, the dependencies of the :ref:`_autogen <_autogen>` +target are composed from - forwarded origin target dependencies (enabled by default via :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`) diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index 0bd4d13209..25c5632394 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst @@ -251,8 +251,8 @@ e.g. in MSVS. :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`: A global ``autogen`` target, that depends on all ``AUTOMOC`` or -:prop_tgt:`AUTOUIC` generated :ref:`_autogen` targets in the project, -will be generated when this variable is ``ON``. +:prop_tgt:`AUTOUIC` generated :ref:`_autogen <_autogen>` +targets in the project, will be generated when this variable is ``ON``. :prop_tgt:`AUTOGEN_PARALLEL`: This target property controls the number of ``moc`` or ``uic`` processes to diff --git a/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst index fec98f6e15..50da7c0a62 100644 --- a/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst +++ b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst @@ -22,7 +22,7 @@ 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 -:ref:`_autogen` target dependencies. +:ref:`_autogen <_autogen>` target dependencies. See :prop_tgt:`AUTOGEN_TARGET_DEPENDS` for reference. By default ``AUTOMOC_DEPEND_FILTERS`` is initialized from diff --git a/Help/prop_tgt/AUTOUIC.rst b/Help/prop_tgt/AUTOUIC.rst index 6f1c85c189..8901de3c24 100644 --- a/Help/prop_tgt/AUTOUIC.rst +++ b/Help/prop_tgt/AUTOUIC.rst @@ -76,8 +76,8 @@ e.g. in MSVS. :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`: A global ``autogen`` target, that depends on all :prop_tgt:`AUTOMOC` or -``AUTOUIC`` generated :ref:`_autogen` targets in the project, -will be generated when this variable is ``ON``. +``AUTOUIC`` generated :ref:`_autogen <_autogen>` +targets in the project, will be generated when this variable is ``ON``. :prop_tgt:`AUTOGEN_PARALLEL`: This target property controls the number of ``moc`` or ``uic`` processes to diff --git a/Help/release/3.14.rst b/Help/release/3.14.rst index 8701474df3..e4a386a2bb 100644 --- a/Help/release/3.14.rst +++ b/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 - :ref:`_autogen` target. + :ref:`_autogen <_autogen>` target. CTest ----- diff --git a/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst b/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst index 52aa891eed..139268b0c6 100644 --- a/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst +++ b/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst @@ -4,14 +4,14 @@ CMAKE_AUTOGEN_ORIGIN_DEPENDS .. versionadded:: 3.14 Switch for forwarding origin target dependencies to the corresponding -:ref:`_autogen` targets. +:ref:`_autogen <_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:`_autogen_timestamp_deps` target instead of the - :ref:`_autogen` target. + the :ref:`_autogen_timestamp_deps <_autogen_timestamp_deps>` + target instead of the :ref:`_autogen <_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 diff --git a/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst index 2bf5f053be..6e2ecc32ac 100644 --- a/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst +++ b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst @@ -7,9 +7,10 @@ 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 :ref:`_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. +:prop_tgt:`AUTOUIC` generated :ref:`_autogen <_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. The name of the global ``autogen`` target can be changed by setting :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET_NAME`. @@ -21,7 +22,8 @@ with Qt. .. note:: - :ref:`_autogen` targets by default inherit their origin target's - dependencies. This might result in unintended dependency target builds when - only :ref:`_autogen` targets are built. A solution is to disable - :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` on the respective origin targets. + :ref:`_autogen <_autogen>` targets by default inherit their + origin target's dependencies. This might result in unintended dependency + target builds when only :ref:`_autogen <_autogen>` targets + are built. A solution is to disable :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` on + the respective origin targets.