ctest_submit: Add support for a "Done" part

Teach CTest to submit Done.xml. Submission of this file indicates to
CDash that a build is complete and no more files will be uploaded. It
contains the build id returned by CDash and the current time.

This file is submitted last for a given build when using the
`ctest_submit()` command.

If submitting by PARTS, use `ctest_submit(PARTS Done)`.

Help/command/ctest_submit.rst

@@ -33,6 +33,7 @@ The options are:
     ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
     Upload     = Files prepared for upload by ctest_upload(), in Upload.xml
     Submit     = nothing
+    Done       = Build is complete, in Done.xml
 
 ``FILES <file>...``
   Specify an explicit list of specific files to be submitted.

Help/release/dev/ctest-done.rst

@@ -0,0 +1,5 @@
+ctest-done
+----------
+
+* The :command:`ctest_submit` command learned a new ``Done`` part that can be used
+  to inform CDash that a build is complete and that no more parts will be uploaded.

Source/CTest/cmCTestSubmitHandler.cxx

@@ -56,6 +56,7 @@ public:
   std::string Filename;
   std::string MD5;
   std::string Message;
+  std::string BuildID;
 
 private:
   std::vector<char> CurrentValue;
@@ -97,6 +98,8 @@ private:
       this->MD5 = this->GetCurrentValue();
     } else if (name == "message") {
       this->Message = this->GetCurrentValue();
+    } else if (name == "buildId") {
+      this->BuildID = this->GetCurrentValue();
     }
   }
 };
@@ -645,6 +648,7 @@ void cmCTestSubmitHandler::ParseResponse(
                  "   Submission failed: " << parser.Message << std::endl);
       return;
     }
+    this->CTest->SetBuildID(parser.BuildID);
   }
   output = cmSystemTools::UpperCase(output);
   if (output.find("WARNING") != std::string::npos) {
@@ -1414,6 +1418,12 @@ int cmCTestSubmitHandler::ProcessHandler()
     files.erase(files.begin() + endPos, files.end());
   }
 
+  // Submit Done.xml last
+  if (this->SubmitPart[cmCTest::PartDone]) {
+    this->CTest->GenerateDoneFile();
+    files.push_back("Done.xml");
+  }
+
   if (ofs) {
     ofs << "Upload files:" << std::endl;
     int cnt = 0;

Source/cmCTest.cxx

@@ -294,6 +294,7 @@ cmCTest::cmCTest()
   this->SuppressUpdatingCTestConfiguration = false;
   this->DartVersion = 1;
   this->DropSiteCDash = false;
+  this->BuildID = "";
   this->OutputTestOutputOnTestFailure = false;
   this->RepeatTests = 1; // default to run each test once
   this->RepeatUntilFail = false;
@@ -320,6 +321,7 @@ cmCTest::cmCTest()
   this->Parts[PartNotes].SetName("Notes");
   this->Parts[PartExtraFiles].SetName("ExtraFiles");
   this->Parts[PartUpload].SetName("Upload");
+  this->Parts[PartDone].SetName("Done");
 
   // Fill the part name-to-id map.
   for (Part p = PartStart; p != PartCount; p = Part(p + 1)) {
@@ -612,6 +614,7 @@ bool cmCTest::InitializeFromCommand(cmCTestStartCommand* command)
   std::string bld_dir = this->GetCTestConfiguration("BuildDirectory");
   this->DartVersion = 1;
   this->DropSiteCDash = false;
+  this->BuildID = "";
   for (Part p = PartStart; p != PartCount; p = Part(p + 1)) {
     this->Parts[p].SubmitFiles.clear();
   }
@@ -1565,6 +1568,24 @@ int cmCTest::GenerateNotesFile(const char* cfiles)
   return this->GenerateNotesFile(files);
 }
 
+int cmCTest::GenerateDoneFile()
+{
+  cmGeneratedFileStream ofs;
+  if (!this->OpenOutputFile(this->CurrentTag, "Done.xml", ofs)) {
+    cmCTestLog(this, ERROR_MESSAGE, "Cannot open done file" << std::endl);
+    return 1;
+  }
+  cmXMLWriter xml(ofs);
+  xml.StartDocument();
+  xml.StartElement("Done");
+  xml.Element("buildId", this->BuildID);
+  xml.Element("time", std::chrono::system_clock::now());
+  xml.EndElement(); // Done
+  xml.EndDocument();
+
+  return 0;
+}
+
 std::string cmCTest::Base64GzipEncodeFile(std::string const& file)
 {
   std::string tarFile = file + "_temp.tar.gz";

Source/cmCTest.h

@@ -50,6 +50,7 @@ public:
     PartNotes,
     PartExtraFiles,
     PartUpload,
+    PartDone,
     PartCount // Update names in constructor when adding a part
   };
 
@@ -373,6 +374,9 @@ public:
   /** Create XML file that contains all the notes specified */
   int GenerateNotesFile(const VectorOfStrings& files);
 
+  /** Create XML file to indicate that build is complete */
+  int GenerateDoneFile();
+
   /** Submit extra files to the server */
   bool SubmitExtraFiles(const char* files);
   bool SubmitExtraFiles(const VectorOfStrings& files);
@@ -405,6 +409,10 @@ public:
   int GetDartVersion() { return this->DartVersion; }
   int GetDropSiteCDash() { return this->DropSiteCDash; }
 
+  /** The Build ID is assigned by CDash */
+  void SetBuildID(const std::string& id) { this->BuildID = id; }
+  std::string GetBuildID() { return this->BuildID; }
+
   /** Add file to be submitted */
   void AddSubmitFile(Part part, const char* name);
   std::vector<std::string> const& GetSubmitFiles(Part part)
@@ -607,6 +615,8 @@ private:
   int DartVersion;
   bool DropSiteCDash;
 
+  std::string BuildID;
+
   std::vector<std::string> InitialCommandLineArguments;
 
   int SubmitIndex;

Tests/RunCMake/ctest_submit/PARTSDone-result.txt

@@ -0,0 +1 @@
+(-1|255)

Tests/RunCMake/ctest_submit/PARTSDone-stderr.txt

@@ -0,0 +1,3 @@
+ *Error when uploading file: .*/Done.xml
+ *Error message was: ([Cc]ould *n.t resolve host:? '?-no-site-'?.*|The requested URL returned error:.*)
+ *Problems when submitting via HTTP

Tests/RunCMake/ctest_submit/RunCMakeTest.cmake

@@ -24,6 +24,7 @@ run_ctest_submit(BadFILES FILES bad-file)
 run_ctest_submit(RepeatRETURN_VALUE RETURN_VALUE res RETURN_VALUE res)
 run_ctest_submit(PARTSCDashUpload PARTS Configure CDASH_UPLOAD)
 run_ctest_submit(PARTSCDashUploadType PARTS Configure CDASH_UPLOAD_TYPE)
+run_ctest_submit(PARTSDone PARTS Done)
 run_ctest_submit(CDashUploadPARTS CDASH_UPLOAD bad-upload PARTS)
 run_ctest_submit(CDashUploadFILES CDASH_UPLOAD bad-upload FILES)
 run_ctest_submit(CDashUploadNone CDASH_UPLOAD)