Merge topic 'help-mark-default-generator'

dfd5ae7da7 Help: Mark default CMake generator with asterisk
6023fe7ff2 ccmake: Append rather than replace Generators section of docs
7408cd3929 cmake: Return generator docs directly

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

8 files changed, 64 insertions, 22 deletions

diff --git a/Source/CursesDialog/ccmake.cxx b/Source/CursesDialog/ccmake.cxx
index 856723a..dbf4a28 100644
--- a/Source/CursesDialog/ccmake.cxx
+++ b/Source/CursesDialog/ccmake.cxx
@@ -5,7 +5,7 @@
 #include "cmCursesMainForm.h"
 #include "cmCursesStandardIncludes.h"
 #include "cmDocumentation.h"
-#include "cmDocumentationEntry.h"
+#include "cmDocumentationEntry.h" // IWYU pragma: keep
 #include "cmState.h"
 #include "cmSystemTools.h"
 #include "cmake.h"
@@ -88,15 +88,14 @@ int main(int argc, char const* const* argv)
     hcm.SetHomeDirectory("");
     hcm.SetHomeOutputDirectory("");
     hcm.AddCMakePaths();
-    std::vector<cmDocumentationEntry> generators;
-    hcm.GetGeneratorDocumentation(generators);
+    auto generators = hcm.GetGeneratorsDocumentation();
     doc.SetName("ccmake");
     doc.SetSection("Name", cmDocumentationName);
     doc.SetSection("Usage", cmDocumentationUsage);
     if (argc == 1) {
       doc.AppendSection("Usage", cmDocumentationUsageNote);
     }
-    doc.SetSection("Generators", generators);
+    doc.AppendSection("Generators", generators);
     doc.PrependSection("Options", cmDocumentationOptions);
     return doc.PrintRequestedDocumentation(std::cout) ? 0 : 1;
   }
diff --git a/Source/QtDialog/CMakeSetup.cxx b/Source/QtDialog/CMakeSetup.cxx
index b4307bb..9f4e48e 100644
--- a/Source/QtDialog/CMakeSetup.cxx
+++ b/Source/QtDialog/CMakeSetup.cxx
@@ -69,8 +69,7 @@ int main(int argc, char** argv)
     hcm.SetHomeOutputDirectory("");
     hcm.AddCMakePaths();
 
-    std::vector<cmDocumentationEntry> generators;
-    hcm.GetGeneratorDocumentation(generators);
+    auto generators = hcm.GetGeneratorsDocumentation();
     doc.SetName("cmake");
     doc.SetSection("Name", cmDocumentationName);
     doc.SetSection("Usage", cmDocumentationUsage);
diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx
index 6a817b4..d4628fa 100644
--- a/Source/cmDocumentation.cxx
+++ b/Source/cmDocumentation.cxx
@@ -43,11 +43,18 @@ static const char* cmDocumentationStandardOptions[][2] = {
   { nullptr, nullptr }
 };
 
-static const char* cmDocumentationGeneratorsHeader[][2] = {
+static const char* cmDocumentationCPackGeneratorsHeader[][2] = {
   { nullptr, "The following generators are available on this platform:" },
   { nullptr, nullptr }
 };
 
+static const char* cmDocumentationCMakeGeneratorsHeader[][2] = {
+  { nullptr,
+    "The following generators are available on this platform (* marks "
+    "default):" },
+  { nullptr, nullptr }
+};
+
 cmDocumentation::cmDocumentation()
 {
   this->addCommonStandardDocSections();
@@ -178,7 +185,7 @@ void cmDocumentation::addCommonStandardDocSections()
 void cmDocumentation::addCMakeStandardDocSections()
 {
   cmDocumentationSection sec{ "Generators" };
-  sec.Append(cmDocumentationGeneratorsHeader);
+  sec.Append(cmDocumentationCMakeGeneratorsHeader);
   this->AllSections.emplace("Generators", std::move(sec));
 }
 
@@ -191,7 +198,9 @@ void cmDocumentation::addCTestStandardDocSections()
 
 void cmDocumentation::addCPackStandardDocSections()
 {
-  addCMakeStandardDocSections();
+  cmDocumentationSection sec{ "Generators" };
+  sec.Append(cmDocumentationCPackGeneratorsHeader);
+  this->AllSections.emplace("Generators", std::move(sec));
 }
 
 bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
diff --git a/Source/cmDocumentationEntry.h b/Source/cmDocumentationEntry.h
index ea43b88..ca323cc 100644
--- a/Source/cmDocumentationEntry.h
+++ b/Source/cmDocumentationEntry.h
@@ -12,6 +12,7 @@ struct cmDocumentationEntry
 {
   std::string Name;
   std::string Brief;
+  char CustomNamePrefix = ' ';
   cmDocumentationEntry() {}
   cmDocumentationEntry(const char* doc[2])
   {
diff --git a/Source/cmDocumentationFormatter.cxx b/Source/cmDocumentationFormatter.cxx
index 678e408..e573c04 100644
--- a/Source/cmDocumentationFormatter.cxx
+++ b/Source/cmDocumentationFormatter.cxx
@@ -5,6 +5,7 @@
 #include "cmDocumentationEntry.h"
 #include "cmDocumentationSection.h"
 
+#include <iomanip>
 #include <ostream>
 #include <string.h>
 #include <string>
@@ -168,7 +169,7 @@ void cmDocumentationFormatter::PrintSection(
   const std::vector<cmDocumentationEntry>& entries = section.GetEntries();
   for (cmDocumentationEntry const& entry : entries) {
     if (!entry.Name.empty()) {
-      os << "  " << entry.Name;
+      os << std::setw(2) << std::left << entry.CustomNamePrefix << entry.Name;
       this->TextIndent = "                                 ";
       int align = static_cast<int>(strlen(this->TextIndent)) - 4;
       for (int i = static_cast<int>(entry.Name.size()); i < align; ++i) {
diff --git a/Source/cmake.cxx b/Source/cmake.cxx
index b44c325..065f6df 100644
--- a/Source/cmake.cxx
+++ b/Source/cmake.cxx
@@ -1527,7 +1527,7 @@ int cmake::ActualConfigure()
   return 0;
 }
 
-void cmake::CreateDefaultGlobalGenerator()
+std::unique_ptr<cmGlobalGenerator> cmake::EvaluateDefaultGlobalGenerator()
 {
 #if defined(_WIN32) && !defined(__CYGWIN__) && !defined(CMAKE_BOOT_MINGW)
   std::string found;
@@ -1580,11 +1580,20 @@ void cmake::CreateDefaultGlobalGenerator()
   if (!gen) {
     gen = new cmGlobalNMakeMakefileGenerator(this);
   }
-  this->SetGlobalGenerator(gen);
-  std::cout << "-- Building for: " << gen->GetName() << "\n";
+  return std::unique_ptr<cmGlobalGenerator>(gen);
 #else
-  this->SetGlobalGenerator(new cmGlobalUnixMakefileGenerator3(this));
+  return cm::make_unique<cmGlobalUnixMakefileGenerator3>(this);
+#endif
+}
+
+void cmake::CreateDefaultGlobalGenerator()
+{
+  auto gen = this->EvaluateDefaultGlobalGenerator();
+#if defined(_WIN32) && !defined(__CYGWIN__) && !defined(CMAKE_BOOT_MINGW)
+  // This print could be unified for all platforms
+  std::cout << "-- Building for: " << gen->GetName() << "\n";
 #endif
+  this->SetGlobalGenerator(gen.release());
 }
 
 void cmake::PreLoadCMakeFiles()
@@ -1932,13 +1941,28 @@ void cmake::SetIsInTryCompile(bool b)
   this->State->SetIsInTryCompile(b);
 }
 
-void cmake::GetGeneratorDocumentation(std::vector<cmDocumentationEntry>& v)
+void cmake::AppendGlobalGeneratorsDocumentation(
+  std::vector<cmDocumentationEntry>& v)
 {
+  const auto defaultGenerator = this->EvaluateDefaultGlobalGenerator();
+  const std::string defaultName = defaultGenerator->GetName();
+  bool foundDefaultOne = false;
+
   for (cmGlobalGeneratorFactory* g : this->Generators) {
     cmDocumentationEntry e;
     g->GetDocumentation(e);
+    if (!foundDefaultOne &&
+        cmSystemTools::StringStartsWith(e.Name, defaultName.c_str())) {
+      e.CustomNamePrefix = '*';
+      foundDefaultOne = true;
+    }
     v.push_back(std::move(e));
   }
+}
+
+void cmake::AppendExtraGeneratorsDocumentation(
+  std::vector<cmDocumentationEntry>& v)
+{
   for (cmExternalMakefileProjectGeneratorFactory* eg : this->ExtraGenerators) {
     const std::string doc = eg->GetDocumentation();
     const std::string name = eg->GetName();
@@ -1964,12 +1988,19 @@ void cmake::GetGeneratorDocumentation(std::vector<cmDocumentationEntry>& v)
   }
 }
 
+std::vector<cmDocumentationEntry> cmake::GetGeneratorsDocumentation()
+{
+  std::vector<cmDocumentationEntry> v;
+  this->AppendGlobalGeneratorsDocumentation(v);
+  this->AppendExtraGeneratorsDocumentation(v);
+  return v;
+}
+
 void cmake::PrintGeneratorList()
 {
 #ifdef CMAKE_BUILD_WITH_CMAKE
   cmDocumentation doc;
-  std::vector<cmDocumentationEntry> generators;
-  this->GetGeneratorDocumentation(generators);
+  auto generators = this->GetGeneratorsDocumentation();
   doc.AppendSection("Generators", generators);
   std::cerr << "\n";
   doc.PrintDocumentation(cmDocumentation::ListGenerators, std::cerr);
diff --git a/Source/cmake.h b/Source/cmake.h
index 38d0c62..9478ad0e 100644
--- a/Source/cmake.h
+++ b/Source/cmake.h
@@ -295,7 +295,7 @@ public:
   cmVariableWatch* GetVariableWatch() { return this->VariableWatch; }
 #endif
 
-  void GetGeneratorDocumentation(std::vector<cmDocumentationEntry>&);
+  std::vector<cmDocumentationEntry> GetGeneratorsDocumentation();
 
   ///! Set/Get a property of this target file
   void SetProperty(const std::string& prop, const char* value);
@@ -534,8 +534,12 @@ private:
   // Print a list of valid generators to stderr.
   void PrintGeneratorList();
 
+  std::unique_ptr<cmGlobalGenerator> EvaluateDefaultGlobalGenerator();
   void CreateDefaultGlobalGenerator();
 
+  void AppendGlobalGeneratorsDocumentation(std::vector<cmDocumentationEntry>&);
+  void AppendExtraGeneratorsDocumentation(std::vector<cmDocumentationEntry>&);
+
   /**
    * Convert a message type between a warning and an error, based on the state
    * of the error output CMake variables, in the cache.
diff --git a/Source/cmakemain.cxx b/Source/cmakemain.cxx
index 5a04eab..10655d5 100644
--- a/Source/cmakemain.cxx
+++ b/Source/cmakemain.cxx
@@ -2,7 +2,7 @@
    file Copyright.txt or https://cmake.org/licensing for details.  */
 
 #include "cmAlgorithms.h"
-#include "cmDocumentationEntry.h"
+#include "cmDocumentationEntry.h" // IWYU pragma: keep
 #include "cmGlobalGenerator.h"
 #include "cmMakefile.h"
 #include "cmState.h"
@@ -227,9 +227,7 @@ int do_cmake(int ac, char const* const* av)
     std::vector<std::string> args(av, av + ac);
     hcm.SetCacheArgs(args);
 
-    std::vector<cmDocumentationEntry> generators;
-
-    hcm.GetGeneratorDocumentation(generators);
+    auto generators = hcm.GetGeneratorsDocumentation();
 
     doc.SetName("cmake");
     doc.SetSection("Name", cmDocumentationName);