ENH: Improved documentation. Also modified behavior of "cmake" to not configure a project in the current directory unless . is given.

Source/CursesDialog/ccmake.cxx

@@ -51,6 +51,13 @@ static const cmDocumentationEntry cmDocumentationDescription[] =
   {0,0,0}
 };
 
+//----------------------------------------------------------------------------
+static const cmDocumentationEntry cmDocumentationOptions[] =
+{
+  CMAKE_STANDARD_OPTIONS_TABLE,
+  {0,0,0}
+};
+
 cmCursesForm* cmCursesForm::CurrentForm=0;
 
 extern "C"
@@ -94,7 +101,7 @@ int main(int argc, char** argv)
     doc.SetNameSection(cmDocumentationName);
     doc.SetUsageSection(cmDocumentationUsage);
     doc.SetDescriptionSection(cmDocumentationDescription);
-    doc.SetOptionsSection(0);
+    doc.SetOptionsSection(cmDocumentationOptions);
     doc.SetCommandsSection(&commands[0]);
     doc.PrintDocumentation(ht, std::cout);
     return 0;

Source/cmake.cxx

@@ -898,27 +898,6 @@ bool cmake::CacheVersionMatches()
 // handle a command line invocation
 int cmake::Run(const std::vector<std::string>& args)
 {
-  // a quick check for args
-  if(args.size() == 1 && !cmSystemTools::FileExists("CMakeLists.txt"))
-    {
-    this->Usage(args[0].c_str());
-    return -1;
-    }
-
-  // look for obvious request for help
-  for(unsigned int i=1; i < args.size(); ++i)
-    {
-    std::string arg = args[i];
-    if(arg.find("-help",0) != std::string::npos ||
-       arg.find("--help",0) != std::string::npos ||
-       arg.find("/?",0) != std::string::npos ||
-       arg.find("-usage",0) != std::string::npos)
-      {
-      this->Usage(args[0].c_str());
-      return -1;
-      }
-    }
-
   // Process the arguments
   this->SetArgs(args);
   
@@ -927,8 +906,9 @@ int cmake::Run(const std::vector<std::string>& args)
   srcList += "/CMakeLists.txt";
   if(!cmSystemTools::FileExists(srcList.c_str()))
     {
-    cmSystemTools::Error("The source directory does not appear to contain CMakeLists.txt\n");
-    this->Usage(args[0].c_str());
+    cmSystemTools::Error(
+      "The source directory does not appear to contain CMakeLists.txt.\n"
+      "Specify --help for usage.");
     return -1;
     }
   

Source/cmake.h

@@ -272,3 +272,22 @@ private:
   const char* m_CCEnvironment;
 };
 
+#define CMAKE_STANDARD_OPTIONS_TABLE \
+  {"-C<initial-cache>", "Pre-load cmake cache from given file.", \
+   "When cmake is first run in an empty build tree, it creates a " \
+   "CMakeCache.txt file and populates it with customizable settings " \
+   "for the project.  This option may be used to specify a file from " \
+   "which to load cache entries before the first pass through " \
+   "the project's cmake listfiles.  The loaded entries take priority " \
+   "over the project's default values."}, \
+  {"-D<var>:<type>=<value>", "Create a cmake cache entry.", \
+   "When cmake is first run in an empty build tree, it creates a " \
+   "CMakeCache.txt file and populates it with customizable settings " \
+   "for the project.  This option may be used to specify a setting " \
+   "that takes priority over the project's default value.  The option " \
+   "may be repeated for as many cache entries as desired."}, \
+  {"-G<generator-name>", "Specify a makefile generator.", \
+   "CMake may support multiple native build systems on certain platforms.  " \
+   "A makefile generator is responsible for generating a particular build " \
+   "system.  Possible generator names are\n" \
+   "  \"Unix Makefiles\" - Standard UNIX Makefiles"}

Source/cmakemain.cxx

@@ -48,7 +48,21 @@ static const cmDocumentationEntry cmDocumentationDescription[] =
 //----------------------------------------------------------------------------
 static const cmDocumentationEntry cmDocumentationOptions[] =
 {
-  {"-i", "Run in wizard mode.", 0},
+  CMAKE_STANDARD_OPTIONS_TABLE,
+  {"-i", "Run in wizard mode.",
+   "Wizard mode runs cmake interactively without a GUI.  The user is "
+   "prompted to answer questions about the project configuration.  "
+   "The answers are used to set cmake cache values."},
+  {0,0,0}
+};
+
+//----------------------------------------------------------------------------
+static const cmDocumentationEntry cmDocumentationNOTE[] =
+{
+  {0,
+   "CMake no longer configures a project when run with no arguments.  "
+   "In order to configure the project in the current directory, run\n"
+   "  cmake .", 0},
   {0,0,0}
 };
 
@@ -71,6 +85,7 @@ int do_cmake(int ac, char** av)
   cmDocumentation doc;
   if(cmDocumentation::Type ht = doc.CheckOptions(ac, av))
     {
+    // Construct and print requested documentation.
     cmake hcm;
     std::vector<cmDocumentationEntry> commands;
     hcm.GetCommandDocumentation(commands);
@@ -80,6 +95,19 @@ int do_cmake(int ac, char** av)
     doc.SetOptionsSection(cmDocumentationOptions);
     doc.SetCommandsSection(&commands[0]);
     doc.PrintDocumentation(ht, std::cout);
+  
+    // If we were run with no arguments, but a CMakeLists.txt file
+    // exists, the user may have been trying to use the old behavior
+    // of cmake to build a project in-source.  Print a message
+    // explaining the change to standard error and return an error
+    // condition in case the program is running from a script.
+    if((ac == 1) && cmSystemTools::FileExists("CMakeLists.txt"))
+      {
+      doc.ClearSections();
+      doc.AddSection("NOTE", cmDocumentationNOTE);
+      doc.Print(cmDocumentation::UsageForm, std::cerr);
+      return 1;
+      }
     return 0;
     }