Commit 2a71a039 authored by Zack Galbreath's avatar Zack Galbreath

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.
parent 43fe736b
......@@ -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.
......
......@@ -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.
......
......@@ -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.
......
......@@ -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);
......
......@@ -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)
......
......@@ -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;
......
......@@ -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" },
......
^Group given in TAG does not match group given in ctest_start\(\)$
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-]+
^Track given in TAG does not match track given in ctest_start\(\)$
^Group given in TAG does not match group given in ctest_start\(\)$
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
......
^CMake Error at .*/Tests/RunCMake/ctest_start/MissingGroupArg/test\.cmake:[0-9]+ \(ctest_start\):
ctest_start GROUP argument missing group name$
^CMake Error at .*/Tests/RunCMake/ctest_start/MissingGroupArgAppend/test\.cmake:[0-9]+ \(ctest_start\):
ctest_start GROUP argument missing group name$
^CMake Error at .*/Tests/RunCMake/ctest_start/MissingGroupArgQuiet/test\.cmake:[0-9]+ \(ctest_start\):
ctest_start GROUP argument missing group name$
^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$
^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$
^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$
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-]+
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-]+
......@@ -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
......
check_tag_contents("^[0-9-]+\nSomeWeirdTrackName\nContinuous\n$")
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment