ctest_update: Add options VERSION_ONLY and VERSION_OVERRIDE

Help/command/ctest_update.rst

@@ -7,6 +7,8 @@ Perform the :ref:`CTest Update Step` as a :ref:`Dashboard Client`.
 
   ctest_update([SOURCE <source-dir>]
                [RETURN_VALUE <result-var>]
+               [VERSION_ONLY]
+               [VERSION_OVERRIDE <version>]
                [CAPTURE_CMAKE_ERROR <result-var>]
                [QUIET])
 
@@ -23,6 +25,21 @@ The options are:
   Store in the ``<result-var>`` variable the number of files
   updated or ``-1`` on error.
 
+``VERSION_ONLY``
+  .. versionadded:: 4.4
+
+  Record the currently checked out revision without updating the source tree to
+  a different version.  This is equivalent to setting the
+  :variable:`CTEST_UPDATE_VERSION_ONLY` variable.
+
+``VERSION_OVERRIDE <version>``
+  .. versionadded:: 4.4
+
+  Report ``<version>`` as the current revision without querying or updating the
+  source tree.  This is equivalent to setting the
+  :variable:`CTEST_UPDATE_VERSION_OVERRIDE` variable, and supersedes
+  ``VERSION_ONLY``.
+
 ``CAPTURE_CMAKE_ERROR <result-var>``
   .. versionadded:: 3.13
 
@@ -38,7 +55,9 @@ The options are:
   the new revision of the repository and any conflicting files
   that were found.
 
-The update always follows the version control branch currently checked
-out in the source directory.  See the :ref:`CTest Update Step`
-documentation for information about variables that change the behavior
-of ``ctest_update()``.
+By default, the update follows the version control branch currently checked
+out in the source directory.  The ``VERSION_ONLY`` and
+``VERSION_OVERRIDE`` options instead record revision information without
+changing the source tree.  See the :ref:`CTest Update Step` documentation
+for information about further variables that change the behavior of
+``ctest_update()``.

Help/manual/ctest.1.rst

@@ -1224,6 +1224,7 @@ Configuration settings to specify the version control tool include:
   to a different version.
 
   * `CTest Script`_ variable: :variable:`CTEST_UPDATE_VERSION_ONLY`
+  * :command:`ctest_update` option: ``VERSION_ONLY``
 
 .. _`UpdateVersionOverride`:
 
@@ -1237,6 +1238,7 @@ Configuration settings to specify the version control tool include:
   CTest not to update the source tree to a different version.
 
   * `CTest Script`_ variable: :variable:`CTEST_UPDATE_VERSION_OVERRIDE`
+  * :command:`ctest_update` option: ``VERSION_OVERRIDE <version>``
 
 Additional configuration settings include:
 

Help/release/dev/ctest-update-version-options.rst

@@ -0,0 +1,8 @@
+ctest-update-version-options
+----------------------------
+
+* The :command:`ctest_update` command gained ``VERSION_ONLY`` and
+  ``VERSION_OVERRIDE`` options to select or report a source revision
+  without requiring the corresponding
+  :variable:`CTEST_UPDATE_VERSION_ONLY` or
+  :variable:`CTEST_UPDATE_VERSION_OVERRIDE` dashboard script variables.

Source/CTest/cmCTestUpdateCommand.cxx

@@ -172,6 +172,13 @@ bool cmCTestUpdateCommand::ExecuteUpdate(UpdateArguments& args,
     updateType = DetermineType(mf.GetSafeDefinition("CTEST_UPDATE_TYPE"));
   }
 
+  std::string const& versionOverride = !args.VersionOverride.empty()
+    ? args.VersionOverride
+    : mf.GetSafeDefinition("CTEST_UPDATE_VERSION_OVERRIDE");
+
+  bool const versionOnly =
+    args.VersionOnly || mf.IsOn("CTEST_UPDATE_VERSION_ONLY");
+
   // If no update command was specified, lookup one for this VCS tool.
   if (updateCommand.empty()) {
     char const* key = TypeToCommandKey(updateType);
@@ -231,7 +238,16 @@ bool cmCTestUpdateCommand::ExecuteUpdate(UpdateArguments& args,
   auto start_time_time = std::chrono::system_clock::now();
   auto elapsed_time_start = std::chrono::steady_clock::now();
 
-  bool updated = vc->Update();
+  bool const updated = [&]() -> bool {
+    if (!versionOverride.empty()) {
+      return vc->UpdateVersionOverride(versionOverride);
+    }
+    if (versionOnly) {
+      return vc->UpdateVersionOnly();
+    }
+    return vc->Update();
+  }();
+
   std::string buildname =
     cmCTest::SafeBuildIdField(mf.GetSafeDefinition("CTEST_BUILD_NAME"));
 
@@ -321,6 +337,8 @@ bool cmCTestUpdateCommand::InitialPass(std::vector<std::string> const& args,
     cmArgumentParser<UpdateArguments>{ MakeBasicParser<UpdateArguments>() }
       .Bind("SOURCE"_s, &UpdateArguments::Source)
       .Bind("RETURN_VALUE"_s, &UpdateArguments::ReturnValue)
+      .Bind("VERSION_ONLY"_s, &UpdateArguments::VersionOnly)
+      .Bind("VERSION_OVERRIDE"_s, &UpdateArguments::VersionOverride)
       .Bind("QUIET"_s, &UpdateArguments::Quiet);
 
   return this->Invoke(parser, args, status, [&](UpdateArguments& a) {

Source/CTest/cmCTestUpdateCommand.h

@@ -20,6 +20,8 @@ protected:
   {
     std::string Source;
     std::string ReturnValue;
+    std::string VersionOverride;
+    bool VersionOnly = false;
     bool Quiet = false;
   };
 

Source/CTest/cmCTestVC.cxx

@@ -138,27 +138,25 @@ void cmCTestVC::CleanupImpl()
 bool cmCTestVC::Update()
 {
   bool result = true;
-
-  // Use the explicitly specified version.
-  std::string versionOverride =
-    this->Makefile->GetSafeDefinition("CTEST_UPDATE_VERSION_OVERRIDE");
-  if (!versionOverride.empty()) {
-    this->SetNewRevision(versionOverride);
-    return true;
-  }
-
-  // if update version only is on then do not actually update,
-  // just note the current version and finish
-  if (!this->Makefile->IsOn("CTEST_UPDATE_VERSION_ONLY")) {
-    result = this->NoteOldRevision() && result;
-    this->Log << "--- Begin Update ---\n";
-    result = this->UpdateImpl() && result;
-    this->Log << "--- End Update ---\n";
-  }
+  result = this->NoteOldRevision() && result;
+  this->Log << "--- Begin Update ---\n";
+  result = this->UpdateImpl() && result;
+  this->Log << "--- End Update ---\n";
   result = this->NoteNewRevision() && result;
   return result;
 }
 
+bool cmCTestVC::UpdateVersionOverride(std::string const& version)
+{
+  this->SetNewRevision(version);
+  return true;
+}
+
+bool cmCTestVC::UpdateVersionOnly()
+{
+  return this->NoteNewRevision();
+}
+
 bool cmCTestVC::NoteOldRevision()
 {
   // We do nothing by default.

Source/CTest/cmCTestVC.h

@@ -45,6 +45,12 @@ public:
   /** Update the working tree to the new revision.  */
   bool Update();
 
+  /** Use the explicitly specified version. */
+  bool UpdateVersionOverride(std::string const& version);
+
+  /** Do not actually update, just note the current version and finish.  */
+  bool UpdateVersionOnly();
+
   /** Get the command line used by the Update method.  */
   std::string const& GetUpdateCommandLine() const
   {

Tests/CTestUpdateCommon.cmake

@@ -246,6 +246,10 @@ function(check_no_update bin_dir)
     if("${r}" MATCHES "PriorRevision")
       message(FATAL_ERROR "Found PriorRevision in no update test")
     endif()
+    if(DEFINED NO_UPDATE_REVISION AND
+       NOT "${r}" MATCHES "<Revision>${NO_UPDATE_REVISION}</Revision>")
+      message(FATAL_ERROR "Missing expected <Revision> in no update test")
+    endif()
     if("${r}" MATCHES "<Revision>")
       set(found_revisions TRUE)
     endif()

Tests/CTestUpdateGIT.cmake.in

@@ -346,6 +346,44 @@ unset(NO_UPDATE)
 
 rewind_source(dash-source)
 
+#-----------------------------------------------------------------------------
+# Test no update with a VERSION_ONLY option.
+message("Running CTest Dashboard Script (No update argument)...")
+
+set(ctest_update_args VERSION_ONLY)
+create_dashboard_script(dash-binary-no-update-arg
+  "# git command configuration
+set(CTEST_GIT_COMMAND \"${GIT}\")
+")
+unset(ctest_update_args)
+
+# Run the dashboard script with CTest.
+set(NO_UPDATE 1)
+run_dashboard_script(dash-binary-no-update-arg)
+unset(NO_UPDATE)
+
+rewind_source(dash-source)
+
+#-----------------------------------------------------------------------------
+# Test reporting a specific revision with VERSION_OVERRIDE.
+message("Running CTest Dashboard Script (Version override)...")
+
+set(ctest_update_args VERSION_OVERRIDE qwertyuiop)
+create_dashboard_script(dash-binary-version-override
+  "# git command configuration
+set(CTEST_GIT_COMMAND \"${GIT}\")
+")
+unset(ctest_update_args)
+
+# Run the dashboard script with CTest.
+set(NO_UPDATE 1)
+set(NO_UPDATE_REVISION qwertyuiop)
+run_dashboard_script(dash-binary-version-override)
+unset(NO_UPDATE_REVISION)
+unset(NO_UPDATE)
+
+rewind_source(dash-source)
+
 #-----------------------------------------------------------------------------
 # Test ctest_update(QUIET)
 message("Running CTest Dashboard Script (update quietly)...")