Merge topic 'help-mark-default-generator'

dfd5ae7d Help: Mark default CMake generator with asterisk
6023fe7f ccmake: Append rather than replace Generators section of docs
7408cd39 cmake: Return generator docs directly
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !2682

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;
   }

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);

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,

Source/cmDocumentationEntry.h

@@ -12,6 +12,7 @@ struct cmDocumentationEntry
 {
   std::string Name;
   std::string Brief;
+  char CustomNamePrefix = ' ';
   cmDocumentationEntry() {}
   cmDocumentationEntry(const char* doc[2])
   {

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) {

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);

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.

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);

Tests/Server/cmakelib.py

@@ -276,6 +276,10 @@ def validateGlobalSettings(cmakeCommand, cmakeCommandPath, data):
   index = cmakeoutput.index('\nGenerators\n\n')
   cmakeGenerators = []
   for line in cmakeoutput[index + 12:].splitlines():
+    if not line:
+      continue
+    if line[0] == '*': # default generator marker
+      line = ' ' + line[1:]
     if not line.startswith('  '):
       continue
     if line.startswith('    '):