ExternalProject: Add support for USES_TERMINAL_PATCH keyword

This brings the patch step into line with all the others which already
had their own `USES_TERMINAL_<step>` keyword. All steps (including
patch) already have their own `LOG_<step>` keyword too, so the lack of
`USES_TERMINAL_PATCH` was inconsistent.

Auxiliary/vim/syntax/cmake.vim

@@ -2056,6 +2056,7 @@ syn keyword cmakeKWExternalProject contained
             \ USES_TERMINAL_CONFIGURE
             \ USES_TERMINAL_DOWNLOAD
             \ USES_TERMINAL_INSTALL
+            \ USES_TERMINAL_PATCH
             \ USES_TERMINAL_TEST
             \ USES_TERMINAL_UPDATE
             \ WORKING_DIRECTORY

Help/release/3.23.rst

@@ -145,6 +145,10 @@ Modules
   ``OBJCXX``, ``CUDA``, and ``HIP`` languages.  It also now honors
   :variable:`CMAKE_SYSROOT` and :variable:`CMAKE_OSX_SYSROOT`.
 
+* The :module:`ExternalProject` module's :command:`ExternalProject_Add`
+  command gained support for a ``USES_TERMINAL_PATCH`` option to give
+  the patch step exclusive terminal access.
+
 * The :module:`FindCUDAToolkit` module now provides a target for
   ``libcufft_static_nocallback``, if found.
 

Modules/ExternalProject.cmake

@@ -407,7 +407,7 @@ External Project Definition
       ``CVS_TAG <tag>``
         Tag to checkout from the CVS repository.
 
-  **Update/Patch Step Options:**
+  **Update Step Options:**
     Whenever CMake is re-run, by default the external project's sources will be
     updated if the download method supports updates (e.g. a git repository
     would be checked if the ``GIT_TAG`` does not refer to a specific commit).
@@ -442,6 +442,7 @@ External Project Definition
       This may cause a step target to be created automatically for the
       ``download`` step.  See policy :policy:`CMP0114`.
 
+  **Patch Step Options:**
     ``PATCH_COMMAND <cmd>...``
       Specifies a custom command to patch the sources after an update. By
       default, no patch command is defined. Note that it can be quite difficult
@@ -750,6 +751,11 @@ External Project Definition
     ``USES_TERMINAL_UPDATE <bool>``
       Give the update step access to the terminal.
 
+    ``USES_TERMINAL_PATCH <bool>``
+      .. versionadded:: 3.23
+
+      Give the patch step access to the terminal.
+
     ``USES_TERMINAL_CONFIGURE <bool>``
       Give the configure step access to the terminal.
 
@@ -3024,6 +3030,13 @@ function(_ep_add_patch_command name)
     set(log "")
   endif()
 
+  get_property(uses_terminal TARGET ${name} PROPERTY _EP_USES_TERMINAL_PATCH)
+  if(uses_terminal)
+    set(uses_terminal USES_TERMINAL 1)
+  else()
+    set(uses_terminal "")
+  endif()
+
   _ep_get_update_disconnected(update_disconnected ${name})
   if(update_disconnected)
     set(patch_dep download)
@@ -3042,6 +3055,7 @@ function(_ep_add_patch_command name)
       WORKING_DIRECTORY \${work_dir}
       DEPENDEES \${patch_dep}
       ${log}
+      ${uses_terminal}
       )"
   )
 endfunction()
@@ -3557,6 +3571,7 @@ function(ExternalProject_Add name)
     #
     USES_TERMINAL_DOWNLOAD
     USES_TERMINAL_UPDATE
+    USES_TERMINAL_PATCH
     USES_TERMINAL_CONFIGURE
     USES_TERMINAL_BUILD
     USES_TERMINAL_INSTALL

Modules/FetchContent.cmake

@@ -920,13 +920,14 @@ function(__FetchContent_directPopulate contentName)
       BUILD_COMMAND
       INSTALL_COMMAND
       TEST_COMMAND
-      # We force both of these to be ON since we are always executing serially
+      # We force these to be ON since we are always executing serially
       # and we want all steps to have access to the terminal in case they
       # need input from the command line (e.g. ask for a private key password)
       # or they want to provide timely progress. We silently absorb and
       # discard these if they are set by the caller.
       USES_TERMINAL_DOWNLOAD
       USES_TERMINAL_UPDATE
+      USES_TERMINAL_PATCH
   )
   set(multiValueArgs "")
 

Modules/FetchContent/CMakeLists.cmake.in

@@ -22,6 +22,7 @@ ExternalProject_Add(${contentName}-populate
                     TEST_COMMAND        ""
                     USES_TERMINAL_DOWNLOAD  YES
                     USES_TERMINAL_UPDATE    YES
+                    USES_TERMINAL_PATCH     YES
 )
 
 @__FETCHCONTENT_COPY_FILE@

Tests/RunCMake/ExternalProject/UsesTerminal-check.cmake

@@ -37,10 +37,11 @@ endmacro()
 # Check Ninja build output to verify whether each target step is in the
 # console pool.
 macro(CheckNinjaTarget _target
-  _download _update _configure _build _test _install
+  _download _update _patch _configure _build _test _install
   )
   CheckNinjaStep(${_target} download ${_download})
   CheckNinjaStep(${_target} update ${_update})
+  CheckNinjaStep(${_target} patch ${_patch})
   CheckNinjaStep(${_target} configure ${_configure})
   CheckNinjaStep(${_target} build ${_build})
   CheckNinjaStep(${_target} test ${_test})
@@ -88,10 +89,10 @@ endif()
 
 # Actual tests:
 CheckNinjaTarget(TerminalTest1
-  true  true  true  true  true  true )
+  true  true  true  true  true  true  true )
 CheckNinjaTarget(TerminalTest2
-  true  false true  false true  false)
+  true  false true  false true  false true)
 CheckNinjaTarget(TerminalTest3
-  false true  false true  false true )
+  false true  false true  false true  false)
 CheckNinjaTarget(TerminalTest4
-  false false false false false false)
+  false false false false false false false)

Tests/RunCMake/ExternalProject/UsesTerminal.cmake

@@ -10,6 +10,7 @@ macro(DoTerminalTest _target)
   ExternalProject_Add(${_target}
     DOWNLOAD_COMMAND "${CMAKE_COMMAND}" -E echo "download"
     UPDATE_COMMAND "${CMAKE_COMMAND}" -E echo "update"
+    PATCH_COMMAND "${CMAKE_COMMAND}" -E echo "patch"
     CONFIGURE_COMMAND "${CMAKE_COMMAND}" -E echo "configure"
     BUILD_COMMAND "${CMAKE_COMMAND}" -E echo "build"
     TEST_COMMAND "${CMAKE_COMMAND}" -E echo "test"
@@ -22,6 +23,7 @@ endmacro()
 DoTerminalTest(TerminalTest1
   USES_TERMINAL_DOWNLOAD 1
   USES_TERMINAL_UPDATE 1
+  USES_TERMINAL_PATCH 1
   USES_TERMINAL_CONFIGURE 1
   USES_TERMINAL_BUILD 1
   USES_TERMINAL_TEST 1
@@ -31,15 +33,16 @@ DoTerminalTest(TerminalTest1
 # USES_TERMINAL on every other step, starting with download
 DoTerminalTest(TerminalTest2
   USES_TERMINAL_DOWNLOAD 1
-  USES_TERMINAL_CONFIGURE 1
+  USES_TERMINAL_PATCH 1
-  USES_TERMINAL_TEST 1
+  USES_TERMINAL_BUILD 1
+  USES_TERMINAL_INSTALL 1
   )
 
 # USES_TERMINAL on every other step, starting with update
 DoTerminalTest(TerminalTest3
   USES_TERMINAL_UPDATE 1
-  USES_TERMINAL_BUILD 1
+  USES_TERMINAL_CONFIGURE 1
-  USES_TERMINAL_INSTALL 1
+  USES_TERMINAL_TEST 1
   )
 
 # USES_TERMINAL on no step