trace: Print control structure "end" commands

Enhance `cmake --trace` (and related modes) by adding a backtrace for
the "end" command after "replaying" control structures.

Expand the unit test to include control structures.

Fixes: #27381

Help/release/dev/trace-end-commands.rst

@@ -0,0 +1,7 @@
+trace-end-commands
+------------------
+
+* The family of :option:`cmake --trace` and related commands now print "end"
+  commands for control structures: :command:`endblock`, :command:`endforeach`,
+  :command:`endfunction`, :command:`endif`, :command:`endmacro`, and
+  :command:`endwhile`.

Source/cmFunctionBlocker.cxx

@@ -11,6 +11,7 @@
 #include "cmExecutionStatus.h"
 #include "cmMakefile.h"
 #include "cmMessageType.h"
+#include "cmake.h"
 
 bool cmFunctionBlocker::IsFunctionBlocked(cmListFileFunction const& lff,
                                           cmExecutionStatus& status)
@@ -49,7 +50,15 @@ bool cmFunctionBlocker::IsFunctionBlocked(cmListFileFunction const& lff,
         mf.IssueMessage(MessageType::AUTHOR_WARNING, e.str());
       }
 
-      return this->Replay(std::move(this->Functions), status);
+      bool replayResult = this->Replay(std::move(this->Functions), status);
+      cmListFileBacktrace endCommandBT =
+        mf.GetBacktrace().Push(closingContext);
+      // if trace is enabled, print a (trivially) evaluated "end" statement
+      if (mf.GetCMakeInstance()->GetTrace()) {
+        mf.PrintCommandTrace(lff, endCommandBT,
+                             cmMakefile::CommandMissingFromStack::Yes);
+      }
+      return replayResult;
     }
   }
 

Tests/RunCMake/CommandLine/trace-redirect-check.cmake

@@ -1,4 +1,4 @@
-file(READ ${RunCMake_SOURCE_DIR}/trace-stderr.txt expected_content)
+file(READ ${RunCMake_SOURCE_DIR}/trace-redirect-stderr-file-contents.txt expected_content)
 string(REGEX REPLACE "\n+$" "" expected_content "${expected_content}")
 
 file(READ ${RunCMake_BINARY_DIR}/redirected.trace actual_content)

Tests/RunCMake/CommandLine/trace-redirect-stderr-file-contents.txt

@@ -0,0 +1,2 @@
+^.*/Tests/RunCMake/CommandLine/CMakeLists\.txt\(1\):  cmake_minimum_required\(VERSION 3\.10 \)
+.*/Tests/RunCMake/CommandLine/CMakeLists\.txt\(2\):  project\(\${RunCMake_TEST} NONE \)

Tests/RunCMake/CommandLine/trace-stderr.txt

@@ -1,2 +1,15 @@
 ^.*/Tests/RunCMake/CommandLine/CMakeLists\.txt\(1\):  cmake_minimum_required\(VERSION 3\.10 \)
 .*/Tests/RunCMake/CommandLine/CMakeLists\.txt\(2\):  project\(\${RunCMake_TEST} NONE \)
+.*
+.*/Tests/RunCMake/CommandLine/trace\.cmake\(1\):  function\(testFlowControl \)
+.*/Tests/RunCMake/CommandLine/trace\.cmake\(9\):  endfunction\(\)
+.*/Tests/RunCMake/CommandLine/trace\.cmake\(11\):  testFlowControl\(\)
+.*/Tests/RunCMake/CommandLine/trace\.cmake\(2\):  foreach\(i RANGE 1 \)
+.*/Tests/RunCMake/CommandLine/trace\.cmake\(3\):  if\(\$\{i\} STREQUAL 1 \)
+.*/Tests/RunCMake/CommandLine/trace\.cmake\(5\):  else\(\)
+.*/Tests/RunCMake/CommandLine/trace\.cmake\(6\):  set\(bar \)
+.*/Tests/RunCMake/CommandLine/trace\.cmake\(7\):  endif\(\)
+.*/Tests/RunCMake/CommandLine/trace\.cmake\(3\):  if\(\$\{i\} STREQUAL 1 \)
+.*/Tests/RunCMake/CommandLine/trace\.cmake\(4\):  set\(foo \)
+.*/Tests/RunCMake/CommandLine/trace\.cmake\(7\):  endif\(\)
+.*/Tests/RunCMake/CommandLine/trace\.cmake\(8\):  endforeach\(\)

Tests/RunCMake/CommandLine/trace.cmake

@@ -0,0 +1,11 @@
+function(testFlowControl)
+  foreach(i RANGE 1)
+    if("${i}" STREQUAL "1")
+      set(foo)
+    else()
+      set(bar)
+    endif()
+  endforeach()
+endfunction()
+
+testFlowControl()