Document and extend the CMAKE_SUPPRESS_REGENERATION variable

Fixes: https://gitlab.kitware.com/cmake/cmake/issues/16815

Help/manual/cmake-variables.7.rst

@@ -178,6 +178,7 @@ Variables that Change Behavior
    /variable/CMAKE_STAGING_PREFIX
    /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
    /variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE
+   /variable/CMAKE_SUPPRESS_REGENERATION
    /variable/CMAKE_SYSROOT
    /variable/CMAKE_SYSROOT_COMPILE
    /variable/CMAKE_SYSROOT_LINK

Help/release/dev/variable-CMAKE_SUPPRESS_REGENERATION.rst

@@ -0,0 +1,6 @@
+variable-CMAKE_SUPPRESS_REGENERATION
+------------------------------------
+
+* The :variable:`CMAKE_SUPPRESS_REGENERATION` variable was extended to support the
+  :generator:`Ninja` and :ref:`Makefile Generators`.
+* The :variable:`CMAKE_SUPPRESS_REGENERATION` variable is now documented.

Help/variable/CMAKE_SUPPRESS_REGENERATION.rst

@@ -0,0 +1,11 @@
+CMAKE_SUPPRESS_REGENERATION
+---------------------------
+
+If CMAKE_SUPPRESS_REGENERATION is ``OFF``, which is default, then CMake adds a
+special target on which all other targets depend that checks the build system
+and optionally re-runs CMake to regenerate the build system when the target
+specification source changes.
+
+If this variable evaluates to ``ON`` at the end of the top-level
+``CMakeLists.txt`` file, CMake will not add the regeneration target to the
+build system or perform any build system checks.

Source/cmGlobalNinjaGenerator.cxx

@@ -1223,11 +1223,13 @@ void cmGlobalNinjaGenerator::WriteUnknownExplicitDependencies(std::ostream& os)
     for (std::string const& file : files) {
       knownDependencies.insert(this->ConvertToNinjaPath(file));
     }
-    // get list files which are implicit dependencies as well and will be phony
-    // for rebuild manifest
-    std::vector<std::string> const& lf = lg->GetMakefile()->GetListFiles();
-    for (std::string const& j : lf) {
-      knownDependencies.insert(this->ConvertToNinjaPath(j));
+    if (!this->GlobalSettingIsOn("CMAKE_SUPPRESS_REGENERATION")) {
+      // get list files which are implicit dependencies as well and will be
+      // phony for rebuild manifest
+      std::vector<std::string> const& lf = lg->GetMakefile()->GetListFiles();
+      for (std::string const& j : lf) {
+        knownDependencies.insert(this->ConvertToNinjaPath(j));
+      }
     }
     std::vector<cmGeneratorExpressionEvaluationFile*> const& ef =
       lg->GetMakefile()->GetEvaluationFiles();
@@ -1335,6 +1337,9 @@ void cmGlobalNinjaGenerator::WriteTargetAll(std::ostream& os)
 
 void cmGlobalNinjaGenerator::WriteTargetRebuildManifest(std::ostream& os)
 {
+  if (this->GlobalSettingIsOn("CMAKE_SUPPRESS_REGENERATION")) {
+    return;
+  }
   cmLocalGenerator* lg = this->LocalGenerators[0];
 
   std::ostringstream cmd;

Source/cmGlobalUnixMakefileGenerator3.cxx

@@ -256,6 +256,10 @@ void cmGlobalUnixMakefileGenerator3::WriteMainMakefile2()
 
 void cmGlobalUnixMakefileGenerator3::WriteMainCMakefile()
 {
+  if (this->GlobalSettingIsOn("CMAKE_SUPPRESS_REGENERATION")) {
+    return;
+  }
+
   // Open the output file.  This should not be copy-if-different
   // because the check-build-system step compares the makefile time to
   // see if the build system must be regenerated.
@@ -525,7 +529,10 @@ void cmGlobalUnixMakefileGenerator3::WriteConvenienceRules(
   std::vector<std::string> depends;
   std::vector<std::string> commands;
 
-  depends.push_back("cmake_check_build_system");
+  bool regenerate = !this->GlobalSettingIsOn("CMAKE_SUPPRESS_REGENERATION");
+  if (regenerate) {
+    depends.push_back("cmake_check_build_system");
+  }
 
   // write the target convenience rules
   for (cmLocalGenerator* localGen : this->LocalGenerators) {
@@ -558,7 +565,9 @@ void cmGlobalUnixMakefileGenerator3::WriteConvenienceRules(
         tmp += "Makefile2";
         commands.push_back(lg->GetRecursiveMakeCall(tmp.c_str(), name));
         depends.clear();
-        depends.push_back("cmake_check_build_system");
+        if (regenerate) {
+          depends.push_back("cmake_check_build_system");
+        }
         lg->WriteMakeRule(ruleFileStream, "Build rule for target.", name,
                           depends, commands, true);
 
@@ -609,7 +618,10 @@ void cmGlobalUnixMakefileGenerator3::WriteConvenienceRules2(
   // write the directory level rules for this local gen
   this->WriteDirectoryRules2(ruleFileStream, lg);
 
-  depends.push_back("cmake_check_build_system");
+  bool regenerate = !this->GlobalSettingIsOn("CMAKE_SUPPRESS_REGENERATION");
+  if (regenerate) {
+    depends.push_back("cmake_check_build_system");
+  }
 
   // for each target Generate the rule files for each target.
   const std::vector<cmGeneratorTarget*>& targets = lg->GetGeneratorTargets();
@@ -715,7 +727,9 @@ void cmGlobalUnixMakefileGenerator3::WriteConvenienceRules2(
         commands.push_back(progCmd.str());
       }
       depends.clear();
-      depends.push_back("cmake_check_build_system");
+      if (regenerate) {
+        depends.push_back("cmake_check_build_system");
+      }
       localName = lg->GetRelativeTargetDirectory(gtarget);
       localName += "/rule";
       lg->WriteMakeRule(ruleFileStream,
@@ -898,7 +912,9 @@ void cmGlobalUnixMakefileGenerator3::WriteHelpRule(
                            "for this Makefile:");
   lg->AppendEcho(commands, "... all (the default if no target is provided)");
   lg->AppendEcho(commands, "... clean");
-  lg->AppendEcho(commands, "... depend");
+  if (!this->GlobalSettingIsOn("CMAKE_SUPPRESS_REGENERATION")) {
+    lg->AppendEcho(commands, "... depend");
+  }
 
   // Keep track of targets already listed.
   std::set<std::string> emittedTargets;

Source/cmGlobalVisualStudio8Generator.cxx

@@ -217,7 +217,7 @@ bool cmGlobalVisualStudio8Generator::AddCheckTarget()
   cmMakefile* mf = lg->GetMakefile();
 
   // Skip the target if no regeneration is to be done.
-  if (mf->IsOn("CMAKE_SUPPRESS_REGENERATION")) {
+  if (this->GlobalSettingIsOn("CMAKE_SUPPRESS_REGENERATION")) {
     return false;
   }
 

Source/cmGlobalXCodeGenerator.cxx

@@ -458,7 +458,7 @@ void cmGlobalXCodeGenerator::AddExtraTargets(
   makeHelper.push_back(""); // placeholder, see below
 
   // Add ZERO_CHECK
-  bool regenerate = !mf->IsOn("CMAKE_SUPPRESS_REGENERATION");
+  bool regenerate = !this->GlobalSettingIsOn("CMAKE_SUPPRESS_REGENERATION");
   bool generateTopLevelProjectOnly =
     mf->IsOn("CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY");
   bool isTopLevel =

Source/cmLocalUnixMakefileGenerator3.cxx

@@ -760,7 +760,8 @@ void cmLocalUnixMakefileGenerator3::WriteSpecialTargetsBottom(
 
   // Write special "cmake_check_build_system" target to run cmake with
   // the --check-build-system flag.
-  {
+  if (!this->GlobalGenerator->GlobalSettingIsOn(
+        "CMAKE_SUPPRESS_REGENERATION")) {
     // Build command to run CMake to check if anything needs regenerating.
     std::string cmakefileName = cmake::GetCMakeFilesDirectoryPostSlash();
     cmakefileName += "Makefile.cmake";
@@ -1580,7 +1581,11 @@ void cmLocalUnixMakefileGenerator3::WriteLocalAllRules(
   std::string recursiveTarget = this->GetCurrentBinaryDirectory();
   recursiveTarget += "/all";
 
-  depends.push_back("cmake_check_build_system");
+  bool regenerate =
+    !this->GlobalGenerator->GlobalSettingIsOn("CMAKE_SUPPRESS_REGENERATION");
+  if (regenerate) {
+    depends.push_back("cmake_check_build_system");
+  }
 
   std::string progressDir = this->GetBinaryDirectory();
   progressDir += cmake::GetCMakeFilesDirectory();
@@ -1643,7 +1648,7 @@ void cmLocalUnixMakefileGenerator3::WriteLocalAllRules(
   if (!noall || cmSystemTools::IsOff(noall)) {
     // Drive the build before installing.
     depends.push_back("all");
-  } else {
+  } else if (regenerate) {
     // At least make sure the build system is up to date.
     depends.push_back("cmake_check_build_system");
   }
@@ -1657,24 +1662,26 @@ void cmLocalUnixMakefileGenerator3::WriteLocalAllRules(
   this->WriteMakeRule(ruleFileStream, "Prepare targets for installation.",
                       "preinstall/fast", depends, commands, true);
 
-  // write the depend rule, really a recompute depends rule
-  depends.clear();
-  commands.clear();
-  std::string cmakefileName = cmake::GetCMakeFilesDirectoryPostSlash();
-  cmakefileName += "Makefile.cmake";
-  {
-    std::string runRule =
-      "$(CMAKE_COMMAND) -H$(CMAKE_SOURCE_DIR) -B$(CMAKE_BINARY_DIR)";
-    runRule += " --check-build-system ";
-    runRule +=
-      this->ConvertToOutputFormat(cmakefileName, cmOutputConverter::SHELL);
-    runRule += " 1";
-    commands.push_back(std::move(runRule));
+  if (regenerate) {
+    // write the depend rule, really a recompute depends rule
+    depends.clear();
+    commands.clear();
+    std::string cmakefileName = cmake::GetCMakeFilesDirectoryPostSlash();
+    cmakefileName += "Makefile.cmake";
+    {
+      std::string runRule =
+        "$(CMAKE_COMMAND) -H$(CMAKE_SOURCE_DIR) -B$(CMAKE_BINARY_DIR)";
+      runRule += " --check-build-system ";
+      runRule +=
+        this->ConvertToOutputFormat(cmakefileName, cmOutputConverter::SHELL);
+      runRule += " 1";
+      commands.push_back(std::move(runRule));
+    }
+    this->CreateCDCommand(commands, this->GetBinaryDirectory(),
+                          this->GetCurrentBinaryDirectory());
+    this->WriteMakeRule(ruleFileStream, "clear depends", "depend", depends,
+                        commands, true);
   }
-  this->CreateCDCommand(commands, this->GetBinaryDirectory(),
-                        this->GetCurrentBinaryDirectory());
-  this->WriteMakeRule(ruleFileStream, "clear depends", "depend", depends,
-                      commands, true);
 }
 
 void cmLocalUnixMakefileGenerator3::ClearDependencies(cmMakefile* mf,

Source/cmLocalVisualStudio7Generator.cxx

@@ -210,7 +210,8 @@ void cmLocalVisualStudio7Generator::CreateSingleVCProj(
 
 cmSourceFile* cmLocalVisualStudio7Generator::CreateVCProjBuildRule()
 {
-  if (this->Makefile->IsOn("CMAKE_SUPPRESS_REGENERATION")) {
+  if (this->GlobalGenerator->GlobalSettingIsOn(
+        "CMAKE_SUPPRESS_REGENERATION")) {
     return nullptr;
   }