STYLE: put a lot of comments into the generated cmake-cache preloading file to aid the user with using it

Alex

1 files changed, 48 insertions, 15 deletions

diff --git a/Source/cmTryRunCommand.cxx b/Source/cmTryRunCommand.cxx
index 11bd037..1e0402d 100644
--- a/Source/cmTryRunCommand.cxx
+++ b/Source/cmTryRunCommand.cxx
@@ -229,13 +229,10 @@ void cmTryRunCommand::DoNotRunExecutable(const std::string& runArgs,
   bool error = false;
   std::string info = "Source file: ";
   info += srcFile + "\n";
-  if (runArgs.size())
-    {
-    info += "Run arguments: ";
-    info += runArgs;
-    info += "\n";
-    }
-  info += "Current CMake stack: " + this->Makefile->GetListFileStack();
+  info += "Run arguments: ";
+  info += runArgs;
+  info += "\n";
+  info += "   Called from: " + this->Makefile->GetListFileStack();
 
   if (this->Makefile->GetDefinition(this->RunResultVariable.c_str()) == 0)
     {
@@ -313,24 +310,60 @@ void cmTryRunCommand::DoNotRunExecutable(const std::string& runArgs,
 
   if (error)
     {
-    static bool firstRun = true;
+    static bool firstTryRun = true;
     std::string fileName =  this->Makefile->GetHomeOutputDirectory();
     fileName += "/TryRunResults.cmake";
-    std::ofstream file(fileName.c_str(), firstRun?std::ios::out : std::ios::app);
+    std::ofstream file(fileName.c_str(), firstTryRun?std::ios::out : std::ios::app);
     if ( file )
       {
-      file << "SET( " << internalRunOutputName << " \""
+      if (firstTryRun)
+        {
+        file << "# This file was generated by CMake because it detected "
+                "TRY_RUN() commands\n"
+                "# in crosscompiling mode. It will be overwritten by the next "
+                "CMake run.\n"
+                "# Copy it to a safe location, set the variables to "
+                "appropriate values\n"
+                "# and use it then to preset the CMake cache (using -C).\n\n";
+        }
+
+      std::string comment ="\n";
+      comment += this->RunResultVariable;
+      comment += "\nindicates whether the executable would have been able to "
+            "run if it was\n"
+            "executed on its target platform. If it would have been able to "
+            "run, set it to\n"
+            "the exit code (in many cases 0 for success). If not, enter "
+            "\"FAILED_TO_RUN\".\n\n";
+      if (out!=0)
+        {
+        comment += internalRunOutputName;
+        comment += "\ncontains the text, which the executable "
+           " would have printed on stdout and stderr.\n"
+           "If the executable would not have been able to run, set it empty.\n"
+           "Otherwise check if the output is evaluated by the "
+           "calling CMake code. If so,\n"
+           "check what the source file would have printed when called with "
+           "the given arguments.\n\n";
+        }
+
+      comment += info;
+      cmsys::SystemTools::ReplaceString(comment, "\n", "\n# ");
+      file << comment << "\n\n";
+
+      file << "SET( " << this->RunResultVariable << " \n     \""
            << this->Makefile->GetDefinition(this->RunResultVariable.c_str())
-           << "\" CACHE STRING \"Result from TRY_RUN\" )\n\n";
+           << "\"\n     CACHE STRING \"Result from TRY_RUN\" )\n\n";
+
       if (out!=0)
         {
-        file << "SET( " << this->RunResultVariable << " \""
-            << this->Makefile->GetDefinition(internalRunOutputName.c_str())
-            << "\" CACHE STRING \"Output from TRY_RUN\" )\n\n";
+        file << "SET( " << internalRunOutputName << " \n     \""
+             << this->Makefile->GetDefinition(internalRunOutputName.c_str())
+             << "\"\n     CACHE STRING \"Output from TRY_RUN\" )\n\n";
         }
       file.close();
       }
-    firstRun = false;
+    firstTryRun = false;
 
     std::string errorMessage = "TRY_RUN() invoked in cross-compiling mode, "
                                "please set the following cache variables "