Merge topic 'autogen_target_docs'

0d80977af4 Autogen: Documentation updates

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !2659

3 files changed, 44 insertions, 25 deletions

diff --git a/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst
index f61089a..022bab5 100644
--- a/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst
+++ b/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst
@@ -5,22 +5,34 @@ Switch for forwarding origin target dependencies to the corresponding
 ``_autogen`` target.
 
 Targets which have their :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` property
-``ON`` have a corresponding ``_autogen`` target which is used to auto generate
+``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,
-such as to create inputs for the ``moc`` or ``uic`` executable.
-
-The dependencies of the ``_autogen`` target are composed from
-
-- the origin target dependencies
-  (by default enabled via :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`)
-- user defined dependencies from :prop_tgt:`AUTOGEN_TARGET_DEPENDS`
-
-:prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` decides whether the origin target
-dependencies should be forwarded to the ``_autogen`` target or not.
+generate-time, it is not possible to define dependencies of it using
+e.g.  :command:`add_dependencies`.  Instead the
+:prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` target property decides whether the origin
+target dependencies should be forwarded to the ``_autogen`` target or not.
 
 By default :prop_tgt:`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
+
+- forwarded origin target dependencies
+  (enabled by default via :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`)
+- additional user defined dependencies from :prop_tgt:`AUTOGEN_TARGET_DEPENDS`
+
 See the :manual:`cmake-qt(7)` manual for more information on using CMake
 with Qt.
+
+Note
+^^^^
+
+Disabling :prop_tgt:`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.
+
+When the ``_autogen`` target doesn't require all the origin target's
+dependencies, and :prop_tgt:`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_TARGET_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst
index 84c2bfe..d5c5e14 100644
--- a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst
+++ b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst
@@ -1,23 +1,22 @@
 AUTOGEN_TARGET_DEPENDS
 ----------------------
 
-Target dependencies of the corresponding ``_autogen`` target.
+Additional target dependencies of the corresponding ``_autogen`` target.
 
 Targets which have their :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` property
-``ON`` have a corresponding ``_autogen`` target which is used to auto generate
+``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,
-such as to create inputs for the ``moc`` or ``uic`` executable.
+generate-time, it is not possible to define dependencies of it using
+e.g.  :command:`add_dependencies`.  Instead the
+:prop_tgt:`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.
 
-The dependencies of the ``_autogen`` target are composed from
+In total the dependencies of the ``_autogen`` target are composed from
 
-- the origin target dependencies
-  (by default enabled via :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`)
-- user defined dependencies from :prop_tgt:`AUTOGEN_TARGET_DEPENDS`
-
-The :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property can be set to a
-list of additional dependencies for the ``_autogen`` target.  Dependencies
-can be target names or file names.
+- forwarded origin target dependencies
+  (enabled by default via :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`)
+- additional user defined dependencies from :prop_tgt:`AUTOGEN_TARGET_DEPENDS`
 
 See the :manual:`cmake-qt(7)` manual for more information on using CMake
 with Qt.
@@ -32,6 +31,6 @@ If :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` depends on a file that is either
 - a :prop_sf:`GENERATED` C++ file that isn't recognized by :prop_tgt:`AUTOMOC`
   and :prop_tgt:`AUTOUIC` because it's skipped by :prop_sf:`SKIP_AUTOMOC`,
   :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` or :policy:`CMP0071` or
-- a file that isn't in the target's sources
+- a file that isn't in the origin target's sources
 
 it must added to :prop_tgt:`AUTOGEN_TARGET_DEPENDS`.
diff --git a/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst
index 75903ab..e82867d 100644
--- a/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst
+++ b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst
@@ -16,3 +16,11 @@ By default :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET` is unset.
 
 See the :manual:`cmake-qt(7)` manual for more information on using CMake
 with Qt.
+
+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.