Merge topic 'autogen-cmp0071-warning'

ff6a5125 Autogen: Doc: Add examples to the SKIP_AUTO* documentations
8831818f Autogen: Doc: Update CMP0071 description
b0775c75 Autogen: Offer solution for CMP0071 in warning message

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

6 files changed, 98 insertions, 45 deletions

diff --git a/Help/policy/CMP0071.rst b/Help/policy/CMP0071.rst
index 61f14dc..ee33aa1 100644
--- a/Help/policy/CMP0071.rst
+++ b/Help/policy/CMP0071.rst
@@ -4,16 +4,15 @@ CMP0071
 Let :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` process
 :prop_sf:`GENERATED` files.
 
-CMake 3.10 and newer process regular *and* :prop_sf:`GENERATED` source files
-in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`.
-In CMake 3.9 and lower, only regular source files were processed in
-:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`,
-:prop_sf:`GENERATED` source files were ignored.
+Since version 3.10, CMake processes **regular** and :prop_sf:`GENERATED`
+source files in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`.
+In earlier CMake versions, only **regular** source files were processed.
+:prop_sf:`GENERATED` source files were ignored silently.
 
-This policy affects how :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` process
-source files that are :prop_sf:`GENERATED`.
+This policy affects how source files that are :prop_sf:`GENERATED`
+get treated in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`.
 
-The ``OLD`` behavior for this policy is to *ignore* :prop_sf:`GENERATED`
+The ``OLD`` behavior for this policy is to ignore :prop_sf:`GENERATED`
 source files in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`.
 
 The ``NEW`` behavior for this policy is to process :prop_sf:`GENERATED`
@@ -21,10 +20,19 @@ source files in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` just like regular
 source files.
 
 .. note::
-  To exclude source files from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`
-  processing, the boolean source file properties
-  :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC` and :prop_sf:`SKIP_AUTOGEN`
-  can be set accordingly.
+
+  To silence the CMP0071 warning source files can be excluded from
+  :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` processing by setting the
+  source file properties :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC` or
+  :prop_sf:`SKIP_AUTOGEN`.
+
+Source skip example::
+
+  # ...
+  set_property(SOURCE /path/to/file1.h PROPERTY SKIP_AUTOMOC ON)
+  set_property(SOURCE /path/to/file2.h PROPERTY SKIP_AUTOUIC ON)
+  set_property(SOURCE /path/to/file3.h PROPERTY SKIP_AUTOGEN ON)
+  # ...
 
 This policy was introduced in CMake version 3.10.  CMake version
 |release| warns when the policy is not set and uses ``OLD`` behavior.
diff --git a/Help/prop_sf/SKIP_AUTOGEN.rst b/Help/prop_sf/SKIP_AUTOGEN.rst
index 6bf2409..f31185a 100644
--- a/Help/prop_sf/SKIP_AUTOGEN.rst
+++ b/Help/prop_sf/SKIP_AUTOGEN.rst
@@ -4,5 +4,14 @@ SKIP_AUTOGEN
 Exclude the source file from :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and
 :prop_tgt:`AUTORCC` processing (for Qt projects).
 
-For finer control see :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC` and
-:prop_sf:`SKIP_AUTORCC`.
+For finer exclusion control see :prop_sf:`SKIP_AUTOMOC`,
+:prop_sf:`SKIP_AUTOUIC` and :prop_sf:`SKIP_AUTORCC`.
+
+EXAMPLE
+^^^^^^^
+
+.. code-block:: cmake
+
+  # ...
+  set_property(SOURCE file.h PROPERTY SKIP_AUTOGEN ON)
+  # ...
diff --git a/Help/prop_sf/SKIP_AUTOMOC.rst b/Help/prop_sf/SKIP_AUTOMOC.rst
index 2245ca6..a929448 100644
--- a/Help/prop_sf/SKIP_AUTOMOC.rst
+++ b/Help/prop_sf/SKIP_AUTOMOC.rst
@@ -3,4 +3,13 @@ SKIP_AUTOMOC
 
 Exclude the source file from :prop_tgt:`AUTOMOC` processing (for Qt projects).
 
-For broader control see :prop_sf:`SKIP_AUTOGEN`
+For broader exclusion control see :prop_sf:`SKIP_AUTOGEN`.
+
+EXAMPLE
+^^^^^^^
+
+.. code-block:: cmake
+
+  # ...
+  set_property(SOURCE file.h PROPERTY SKIP_AUTOMOC ON)
+  # ...
diff --git a/Help/prop_sf/SKIP_AUTORCC.rst b/Help/prop_sf/SKIP_AUTORCC.rst
index 394d8f8..bccccfc 100644
--- a/Help/prop_sf/SKIP_AUTORCC.rst
+++ b/Help/prop_sf/SKIP_AUTORCC.rst
@@ -3,4 +3,13 @@ SKIP_AUTORCC
 
 Exclude the source file from :prop_tgt:`AUTORCC` processing (for Qt projects).
 
-For broader control see :prop_sf:`SKIP_AUTOGEN`
+For broader exclusion control see :prop_sf:`SKIP_AUTOGEN`.
+
+EXAMPLE
+^^^^^^^
+
+.. code-block:: cmake
+
+  # ...
+  set_property(SOURCE file.qrc PROPERTY SKIP_AUTORCC ON)
+  # ...
diff --git a/Help/prop_sf/SKIP_AUTOUIC.rst b/Help/prop_sf/SKIP_AUTOUIC.rst
index 50f78ef..4eda726 100644
--- a/Help/prop_sf/SKIP_AUTOUIC.rst
+++ b/Help/prop_sf/SKIP_AUTOUIC.rst
@@ -3,4 +3,13 @@ SKIP_AUTOUIC
 
 Exclude the source file from :prop_tgt:`AUTOUIC` processing (for Qt projects).
 
-For broader control see :prop_sf:`SKIP_AUTOGEN`
+For broader exclusion control see :prop_sf:`SKIP_AUTOGEN`.
+
+EXAMPLE
+^^^^^^^
+
+.. code-block:: cmake
+
+  # ...
+  set_property(SOURCE file.h PROPERTY SKIP_AUTOUIC ON)
+  # ...
diff --git a/Source/cmQtAutoGeneratorInitializer.cxx b/Source/cmQtAutoGeneratorInitializer.cxx
index 9befd65..1ce350f 100644
--- a/Source/cmQtAutoGeneratorInitializer.cxx
+++ b/Source/cmQtAutoGeneratorInitializer.cxx
@@ -662,23 +662,24 @@ void cmQtAutoGeneratorInitializer::InitializeAutogenTarget(
   {
     std::vector<std::string> toolNames;
     if (digest.MocEnabled) {
-      toolNames.push_back("MOC");
+      toolNames.emplace_back("MOC");
     }
     if (digest.UicEnabled) {
-      toolNames.push_back("UIC");
+      toolNames.emplace_back("UIC");
     }
     if (digest.RccEnabled) {
-      toolNames.push_back("RCC");
+      toolNames.emplace_back("RCC");
     }
 
-    std::string tools = toolNames[0];
+    std::string tools = toolNames.front();
     toolNames.erase(toolNames.begin());
-    while (toolNames.size() > 1) {
-      tools += ", " + toolNames[0];
-      toolNames.erase(toolNames.begin());
-    }
-    if (toolNames.size() == 1) {
-      tools += " and " + toolNames[0];
+    if (!toolNames.empty()) {
+      while (toolNames.size() > 1) {
+        tools += ", ";
+        tools += toolNames.front();
+        toolNames.erase(toolNames.begin());
+      }
+      tools += " and " + toolNames.front();
     }
     autogenComment = "Automatic " + tools + " for target " + target->GetName();
   }
@@ -809,27 +810,35 @@ void cmQtAutoGeneratorInitializer::InitializeAutogenTarget(
         msg += cmPolicies::GetPolicyWarning(cmPolicies::CMP0071);
         msg += "\n";
         std::string tools;
-        if (digest.MocEnabled) {
-          tools += "AUTOMOC";
-        }
-        if (digest.UicEnabled) {
-          if (!tools.empty()) {
-            tools += ",";
-          }
-          tools += "AUTOUIC";
+        std::string property;
+        if (digest.MocEnabled && digest.UicEnabled) {
+          tools = "AUTOMOC and AUTOUIC";
+          property = "SKIP_AUTOGEN";
+        } else if (digest.MocEnabled) {
+          tools = "AUTOMOC";
+          property = "SKIP_AUTOMOC";
+        } else if (digest.UicEnabled) {
+          tools = "AUTOUIC";
+          property = "SKIP_AUTOUIC";
         }
-        if (!generatedHeaders.empty()) {
-          msg.append(tools).append(": Ignoring GENERATED header file(s):\n");
-          for (std::string const& absFile : generatedHeaders) {
-            msg.append("  ").append(cmQtAutoGen::Quoted(absFile)).append("\n");
-          }
+        msg += "For compatibility, CMake is excluding the GENERATED source "
+               "file(s):\n";
+        for (const std::string& absFile : generatedHeaders) {
+          msg.append("  ").append(cmQtAutoGen::Quoted(absFile)).append("\n");
         }
-        if (!generatedSources.empty()) {
-          msg.append(tools).append(": Ignoring GENERATED source file(s):\n");
-          for (std::string const& absFile : generatedSources) {
-            msg.append("  ").append(cmQtAutoGen::Quoted(absFile)).append("\n");
-          }
+        for (const std::string& absFile : generatedSources) {
+          msg.append("  ").append(cmQtAutoGen::Quoted(absFile)).append("\n");
         }
+        msg += "from processing by ";
+        msg += tools;
+        msg +=
+          ". If any of the files should be processed, set CMP0071 to NEW. "
+          "If any of the files should not be processed, "
+          "explicitly exclude them by setting the source file property ";
+        msg += property;
+        msg += ":\n  set_property(SOURCE file.h PROPERTY ";
+        msg += property;
+        msg += " ON)\n";
         makefile->IssueMessage(cmake::AUTHOR_WARNING, msg);
       }
     }