ctest: rename TRACK to GROUP

Update command-line options, script variables, and documentation to use
the term "group" instead of "track". The old terms are still available
for now, but they are now undocumented.

This makes our terminology more consistent with CDash. The goal of this
change is to make it more clear to our users how CTest and CDash interact
with each other.

Help/command/ctest_start.rst

@@ -5,9 +5,9 @@ Starts the testing for a given model
 
 ::
 
-  ctest_start(<model> [<source> [<binary>]] [TRACK <track>] [QUIET])
+  ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET])
 
-  ctest_start([<model> [<source> [<binary>]]] [TRACK <track>] APPEND [QUIET])
+  ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET])
 
 Starts the testing for a given model.  The command should be called
 after the binary directory is initialized.
@@ -26,20 +26,21 @@ The parameters are as follows:
   Set the binary directory. If not specified, the value of
   :variable:`CTEST_BINARY_DIRECTORY` is used instead.
 
-``TRACK <track>``
-  If ``TRACK`` is used, the submissions will go to the specified track on the
-  CDash server. If no ``TRACK`` is specified, the name of the model is used by
-  default.
+``GROUP <group>``
+  If ``GROUP`` is used, the submissions will go to the specified group on the
+  CDash server. If no ``GROUP`` is specified, the name of the model is used by
+  default. This replaces the deprecated option ``TRACK``. Despite the name
+  change its behavior is unchanged.
 
 ``APPEND``
   If ``APPEND`` is used, the existing ``TAG`` is used rather than creating a new
   one based on the current time stamp. If you use ``APPEND``, you can omit the
-  ``<model>`` and ``TRACK <track>`` parameters, because they will be read from
+  ``<model>`` and ``GROUP <group>`` parameters, because they will be read from
   the generated ``TAG`` file. For example:
 
   .. code-block:: cmake
 
-    ctest_start(Experimental TRACK TrackExperimental)
+    ctest_start(Experimental GROUP GroupExperimental)
 
   Later, in another ``ctest -S`` script:
 
@@ -48,11 +49,11 @@ The parameters are as follows:
     ctest_start(APPEND)
 
   When the second script runs ``ctest_start(APPEND)``, it will read the
-  ``Experimental`` model and ``TrackExperimental`` track from the ``TAG`` file
+  ``Experimental`` model and ``GroupExperimental`` group from the ``TAG`` file
   generated by the first ``ctest_start()`` command. Please note that if you
-  call ``ctest_start(APPEND)`` and specify a different model or track than
+  call ``ctest_start(APPEND)`` and specify a different model or group than
   in the first ``ctest_start()`` command, a warning will be issued, and the
-  new model and track will be used.
+  new model and group will be used.
 
 ``QUIET``
   If ``QUIET`` is used, CTest will suppress any non-error messages that it
@@ -65,11 +66,11 @@ equivalent:
 
 .. code-block:: cmake
 
-  ctest_start(Experimental path/to/source path/to/binary TRACK SomeTrack QUIET APPEND)
+  ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND)
 
-  ctest_start(TRACK SomeTrack Experimental QUIET path/to/source APPEND path/to/binary)
+  ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary)
 
-  ctest_start(APPEND QUIET Experimental path/to/source TRACK SomeTrack path/to/binary)
+  ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary)
 
 However, for the sake of readability, it is recommended that you order your
 parameters in the order listed at the top of this page.

Help/manual/ctest.1.rst

@@ -482,14 +482,17 @@ a `CDash`_ server. The command-line signature used to submit to `CDash`_ is::
 
 Options for Dashboard Client include:
 
-``--track <track>``
- Specify the track to submit dashboard to
+``--group <group>``
+ Specify what group you'd like to submit results to
 
- Submit dashboard to specified track instead of default one.  By
+ Submit dashboard to specified group instead of default one.  By
  default, the dashboard is submitted to Nightly, Experimental, or
- Continuous track, but by specifying this option, the track can be
+ Continuous group, but by specifying this option, the group can be
  arbitrary.
 
+ This replaces the deprecated option ``--track``.
+ Despite the name change its behavior is unchanged.
+
 ``-A <file>, --add-notes <file>``
  Add a notes file with submission.
 

Source/CTest/cmCTestStartCommand.cxx

@@ -33,14 +33,16 @@ bool cmCTestStartCommand::InitialPass(std::vector<std::string> const& args,
   const char* bld_dir = nullptr;
 
   while (cnt < args.size()) {
-    if (args[cnt] == "TRACK") {
+    if (args[cnt] == "GROUP" || args[cnt] == "TRACK") {
       cnt++;
       if (cnt >= args.size() || args[cnt] == "APPEND" ||
           args[cnt] == "QUIET") {
-        this->SetError("TRACK argument missing track name");
+        std::ostringstream e;
+        e << args[cnt - 1] << " argument missing group name";
+        this->SetError(e.str());
         return false;
       }
-      this->CTest->SetSpecificTrack(args[cnt].c_str());
+      this->CTest->SetSpecificGroup(args[cnt].c_str());
       cnt++;
     } else if (args[cnt] == "APPEND") {
       cnt++;
@@ -113,10 +115,10 @@ bool cmCTestStartCommand::InitialPass(std::vector<std::string> const& args,
                          << "   Build directory: " << bld_dir << std::endl,
                        this->Quiet);
   }
-  const char* track = this->CTest->GetSpecificTrack();
-  if (track) {
+  const char* group = this->CTest->GetSpecificGroup();
+  if (group) {
     cmCTestOptionalLog(this->CTest, HANDLER_OUTPUT,
-                       "   Track: " << track << std::endl, this->Quiet);
+                       "   Group: " << group << std::endl, this->Quiet);
   }
 
   // Log startup actions.

Source/CTest/cmCTestSubmitHandler.cxx

@@ -569,6 +569,11 @@ int cmCTestSubmitHandler::HandleCDashUploadFile(std::string const& file,
       << curl.Escape(this->CTest->GetCTestConfiguration("BuildName")) << "&"
       << "site=" << curl.Escape(this->CTest->GetCTestConfiguration("Site"))
       << "&"
+      << "group=" << curl.Escape(this->CTest->GetTestModelString())
+      << "&"
+      // For now, we send both "track" and "group" to CDash in case we're
+      // submitting to an older instance that still expects the prior
+      // terminology.
       << "track=" << curl.Escape(this->CTest->GetTestModelString()) << "&"
       << "starttime=" << timeNow << "&"
       << "endtime=" << timeNow << "&"
@@ -837,10 +842,10 @@ int cmCTestSubmitHandler::ProcessHandler()
   }
   cmCTestOptionalLog(this->CTest, HANDLER_OUTPUT, "Submit files\n",
                      this->Quiet);
-  const char* specificTrack = this->CTest->GetSpecificTrack();
-  if (specificTrack) {
+  const char* specificGroup = this->CTest->GetSpecificGroup();
+  if (specificGroup) {
     cmCTestOptionalLog(this->CTest, HANDLER_OUTPUT,
-                       "   Send to track: " << specificTrack << std::endl,
+                       "   Send to group: " << specificGroup << std::endl,
                        this->Quiet);
   }
   this->SetLogFile(&ofs);

Source/cmCTest.cxx

@@ -155,7 +155,7 @@ struct cmCTest::Private
   bool TomorrowTag = false;
 
   int TestModel = cmCTest::EXPERIMENTAL;
-  std::string SpecificTrack;
+  std::string SpecificGroup;
 
   cmDuration TimeOut = cmDuration::zero();
 
@@ -508,10 +508,10 @@ int cmCTest::Initialize(const char* binary_dir, cmCTestStartCommand* command)
             day != lctime->tm_mday) {
           tag.clear();
         }
-        std::string track;
-        if (cmSystemTools::GetLineFromStream(tfin, track) &&
+        std::string group;
+        if (cmSystemTools::GetLineFromStream(tfin, group) &&
             !this->Impl->Parts[PartStart] && !command) {
-          this->Impl->SpecificTrack = track;
+          this->Impl->SpecificGroup = group;
         }
         std::string model;
         if (cmSystemTools::GetLineFromStream(tfin, model) &&
@@ -564,13 +564,13 @@ int cmCTest::Initialize(const char* binary_dir, cmCTestStartCommand* command)
         }
       }
     } else {
-      std::string track;
+      std::string group;
       std::string modelStr;
       int model = cmCTest::UNKNOWN;
 
       if (tfin) {
         cmSystemTools::GetLineFromStream(tfin, tag);
-        cmSystemTools::GetLineFromStream(tfin, track);
+        cmSystemTools::GetLineFromStream(tfin, group);
         if (cmSystemTools::GetLineFromStream(tfin, modelStr)) {
           model = GetTestModelFromString(modelStr.c_str());
         }
@@ -605,15 +605,15 @@ int cmCTest::Initialize(const char* binary_dir, cmCTestStartCommand* command)
                            quiet);
       }
 
-      if (!this->Impl->SpecificTrack.empty() &&
-          track != this->Impl->SpecificTrack) {
+      if (!this->Impl->SpecificGroup.empty() &&
+          group != this->Impl->SpecificGroup) {
         cmCTestOptionalLog(this, WARNING,
-                           "Track given in TAG does not match "
-                           "track given in ctest_start()"
+                           "Group given in TAG does not match "
+                           "group given in ctest_start()"
                              << std::endl,
                            quiet);
       } else {
-        this->Impl->SpecificTrack = track;
+        this->Impl->SpecificGroup = group;
       }
 
       cmCTestOptionalLog(this, OUTPUT,
@@ -1021,8 +1021,8 @@ int cmCTest::ProcessSteps()
 
 std::string cmCTest::GetTestModelString()
 {
-  if (!this->Impl->SpecificTrack.empty()) {
-    return this->Impl->SpecificTrack;
+  if (!this->Impl->SpecificGroup.empty()) {
+    return this->Impl->SpecificGroup;
   }
   switch (this->Impl->TestModel) {
     case cmCTest::NIGHTLY:
@@ -1908,9 +1908,15 @@ bool cmCTest::HandleCommandLineArguments(size_t& i,
     this->Impl->Debug = true;
     this->Impl->ShowLineNumbers = true;
   }
+  if (this->CheckArgument(arg, "--group") && i < args.size() - 1) {
+    i++;
+    this->Impl->SpecificGroup = args[i];
+  }
+  // This is an undocumented / deprecated option.
+  // "Track" has been renamed to "Group".
   if (this->CheckArgument(arg, "--track") && i < args.size() - 1) {
     i++;
-    this->Impl->SpecificTrack = args[i];
+    this->Impl->SpecificGroup = args[i];
   }
   if (this->CheckArgument(arg, "--show-line-numbers")) {
     this->Impl->ShowLineNumbers = true;
@@ -2769,21 +2775,21 @@ std::vector<std::string>& cmCTest::GetInitialCommandLineArguments()
   return this->Impl->InitialCommandLineArguments;
 }
 
-const char* cmCTest::GetSpecificTrack()
+const char* cmCTest::GetSpecificGroup()
 {
-  if (this->Impl->SpecificTrack.empty()) {
+  if (this->Impl->SpecificGroup.empty()) {
     return nullptr;
   }
-  return this->Impl->SpecificTrack.c_str();
+  return this->Impl->SpecificGroup.c_str();
 }
 
-void cmCTest::SetSpecificTrack(const char* track)
+void cmCTest::SetSpecificGroup(const char* group)
 {
-  if (!track) {
-    this->Impl->SpecificTrack.clear();
+  if (!group) {
+    this->Impl->SpecificGroup.clear();
     return;
   }
-  this->Impl->SpecificTrack = track;
+  this->Impl->SpecificGroup = group;
 }
 
 void cmCTest::SetFailover(bool failover)

Source/cmCTest.h

@@ -404,9 +404,9 @@ public:
 
   std::vector<std::string>& GetInitialCommandLineArguments();
 
-  /** Set the track to submit to */
-  void SetSpecificTrack(const char* track);
-  const char* GetSpecificTrack();
+  /** Set the group to submit to */
+  void SetSpecificGroup(const char* group);
+  const char* GetSpecificGroup();
 
   void SetFailover(bool failover);
   bool GetFailover() const;

Source/ctest.cxx

@@ -83,7 +83,9 @@ static const char* cmDocumentationOptions[][2] = {
   { "-T <action>, --test-action <action>",
     "Sets the dashboard action to "
     "perform" },
-  { "--track <track>", "Specify the track to submit dashboard to" },
+  { "--group <group>",
+    "Specify what build group on the dashboard you'd like to "
+    "submit results to." },
   { "-S <script>, --script <script>",
     "Execute a dashboard for a "
     "configuration" },

Tests/RunCMake/ctest_start/AppendDifferentGroup-stderr.txt

@@ -0,0 +1 @@
+^Group given in TAG does not match group given in ctest_start\(\)$

Tests/RunCMake/ctest_start/AppendDifferentGroup-stdout.txt

@@ -0,0 +1,8 @@
+Run dashboard with to-be-determined model
+   Source directory: .*/Tests/RunCMake/ctest_start/AppendDifferentGroup
+   Build directory: .*/Tests/RunCMake/ctest_start/AppendDifferentGroup-build
+   Group: ExperimentalDifferent
+   Site: test-site
+   Build name: test-build-name
+  Use existing tag: 19551112-2204 - ExperimentalDifferent
+   Use ExperimentalDifferent tag: [0-9-]+

Tests/RunCMake/ctest_start/AppendDifferentTrack-stderr.txt

@@ -1 +1 @@
-^Track given in TAG does not match track given in ctest_start\(\)$
+^Group given in TAG does not match group given in ctest_start\(\)$

Tests/RunCMake/ctest_start/AppendDifferentTrack-stdout.txt

@@ -1,7 +1,7 @@
 Run dashboard with to-be-determined model
    Source directory: .*/Tests/RunCMake/ctest_start/AppendDifferentTrack
    Build directory: .*/Tests/RunCMake/ctest_start/AppendDifferentTrack-build
-   Track: ExperimentalDifferent
+   Group: ExperimentalDifferent
    Site: test-site
    Build name: test-build-name
   Use existing tag: 19551112-2204 - ExperimentalDifferent

Tests/RunCMake/ctest_start/MissingGroupArg-result.txt

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

Tests/RunCMake/ctest_start/MissingGroupArg-stderr.txt

@@ -0,0 +1,2 @@
+^CMake Error at .*/Tests/RunCMake/ctest_start/MissingGroupArg/test\.cmake:[0-9]+ \(ctest_start\):
+  ctest_start GROUP argument missing group name$

Tests/RunCMake/ctest_start/MissingGroupArgAppend-result.txt

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

Tests/RunCMake/ctest_start/MissingGroupArgAppend-stderr.txt

@@ -0,0 +1,2 @@
+^CMake Error at .*/Tests/RunCMake/ctest_start/MissingGroupArgAppend/test\.cmake:[0-9]+ \(ctest_start\):
+  ctest_start GROUP argument missing group name$

Tests/RunCMake/ctest_start/MissingGroupArgQuiet-result.txt

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

Tests/RunCMake/ctest_start/MissingGroupArgQuiet-stderr.txt

@@ -0,0 +1,2 @@
+^CMake Error at .*/Tests/RunCMake/ctest_start/MissingGroupArgQuiet/test\.cmake:[0-9]+ \(ctest_start\):
+  ctest_start GROUP argument missing group name$

Tests/RunCMake/ctest_start/MissingTrackArg-stderr.txt

@@ -1,2 +1,2 @@
 ^CMake Error at .*/Tests/RunCMake/ctest_start/MissingTrackArg/test\.cmake:[0-9]+ \(ctest_start\):
-  ctest_start TRACK argument missing track name$
+  ctest_start TRACK argument missing group name$

Tests/RunCMake/ctest_start/MissingTrackArgAppend-stderr.txt

@@ -1,2 +1,2 @@
 ^CMake Error at .*/Tests/RunCMake/ctest_start/MissingTrackArgAppend/test\.cmake:[0-9]+ \(ctest_start\):
-  ctest_start TRACK argument missing track name$
+  ctest_start TRACK argument missing group name$

Tests/RunCMake/ctest_start/MissingTrackArgQuiet-stderr.txt

@@ -1,2 +1,2 @@
 ^CMake Error at .*/Tests/RunCMake/ctest_start/MissingTrackArgQuiet/test\.cmake:[0-9]+ \(ctest_start\):
-  ctest_start TRACK argument missing track name$
+  ctest_start TRACK argument missing group name$

Tests/RunCMake/ctest_start/NoAppendDifferentGroup-stdout.txt

@@ -0,0 +1,7 @@
+Run dashboard with model Experimental
+   Source directory: .*/Tests/RunCMake/ctest_start/NoAppendDifferentGroup
+   Build directory: .*/Tests/RunCMake/ctest_start/NoAppendDifferentGroup-build
+   Group: ExperimentalDifferent
+   Site: test-site
+   Build name: test-build-name
+   Use ExperimentalDifferent tag: [0-9-]+

Tests/RunCMake/ctest_start/NoAppendDifferentTrack-stdout.txt

@@ -1,7 +1,7 @@
 Run dashboard with model Experimental
    Source directory: .*/Tests/RunCMake/ctest_start/NoAppendDifferentTrack
    Build directory: .*/Tests/RunCMake/ctest_start/NoAppendDifferentTrack-build
-   Track: ExperimentalDifferent
+   Group: ExperimentalDifferent
    Site: test-site
    Build name: test-build-name
    Use ExperimentalDifferent tag: [0-9-]+

Tests/RunCMake/ctest_start/RunCMakeTest.cmake

@@ -26,18 +26,24 @@ run_ctest_start(WriteModelToTagExperimental Experimental QUIET)
 run_ctest_start(WriteModelToTagContinuous Continuous QUIET)
 run_ctest_start(WriteModelToTagNightly Nightly QUIET)
 run_ctest_start(WriteModelToTagNoMatchingTrack Continuous TRACK SomeWeirdTrackName QUIET)
+run_ctest_start(WriteModelToTagNoMatchingGroup Continuous GROUP SomeWeirdTrackName QUIET)
 run_ctest_start(AppendSameModel Continuous APPEND)
 run_ctest_start(AppendDifferentModel Experimental APPEND)
 run_ctest_start(AppendNoModel APPEND)
 run_ctest_start(AppendDifferentTrack TRACK ExperimentalDifferent APPEND)
+run_ctest_start(AppendDifferentGroup GROUP ExperimentalDifferent APPEND)
 run_ctest_start(NoAppendDifferentTrack Experimental TRACK ExperimentalDifferent)
+run_ctest_start(NoAppendDifferentGroup Experimental GROUP ExperimentalDifferent)
 run_ctest_start(AppendNoMatchingTrack Continuous APPEND)
 run_ctest_start(AppendOldContinuous Continuous APPEND)
 run_ctest_start(AppendOldNoModel APPEND)
 run_ctest_start(NoModel QUIET)
 run_ctest_start(MissingTrackArg Experimental TRACK)
+run_ctest_start(MissingGroupArg Experimental GROUP)
 run_ctest_start(MissingTrackArgAppend Experimental TRACK APPEND)
+run_ctest_start(MissingGroupArgAppend Experimental GROUP APPEND)
 run_ctest_start(MissingTrackArgQuiet Experimental TRACK QUIET)
+run_ctest_start(MissingGroupArgQuiet Experimental GROUP QUIET)
 run_ctest_start(TooManyArgs Experimental
                 ${RunCMake_BINARY_DIR}/TooManyArgs-build
                 ${RunCMake_BINARY_DIR}/TooManyArgs-build

Tests/RunCMake/ctest_start/WriteModelToTagNoMatchingGroup-check.cmake

@@ -0,0 +1 @@
+check_tag_contents("^[0-9-]+\nSomeWeirdTrackName\nContinuous\n$")