From 4cd4e858a830d62f092b38ef45be52cdda4d6cc0 Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Sun, 25 Oct 2026 20:09:26 -0400 Subject: [PATCH] Tests/RunCMake: Document toolchain inspection pattern Make it more accessible for reuse in future test cases. --- Tests/RunCMake/README.rst | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/Tests/RunCMake/README.rst b/Tests/RunCMake/README.rst index 5d52cdfa70..7b079ae0cf 100644 --- a/Tests/RunCMake/README.rst +++ b/Tests/RunCMake/README.rst @@ -249,6 +249,41 @@ runs CMake to configure the case's project. The second step runs build tool's ``stderr`` into its ``stdout``. Note that each call uses a unique case name so that expected results can be expressed individually. +Inspecting the Toolchain +======================== + +A ``RunCMakeTest.cmake`` script runs in CMake script mode, so it does not +have information about the toolchain, such as compiler IDs, versions, +or platform-specific variables. When test case selection or expected +results depend on such information, a conventional ``Inspect`` case can +be used to obtain it:: + + run_cmake(Inspect) + include("${RunCMake_BINARY_DIR}/Inspect-build/info.cmake") + +where ``/Inspect.cmake`` enables the needed languages and writes +the values of interest to an ``info.cmake`` file in its build tree:: + + enable_language(C) + + set(info "") + foreach(var + CMAKE_C_COMPILER_ID + CMAKE_C_COMPILER_VERSION + ) + if(DEFINED ${var}) + string(APPEND info "set(${var} \"${${var}}\")\n") + endif() + endforeach() + + file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/info.cmake" "${info}") + +After the ``include()``, the ``RunCMakeTest.cmake`` script may use the +forwarded variables to decide which cases to run or which expected +results to use. Values computed in ``Inspect.cmake`` from other project +state may be forwarded the same way. If the inspection needs extra +configuration, use ``run_cmake_with_options(Inspect ...)`` instead. + Running a Test ==============