Tests/RunCMake: Document commands/variables available to RunCMakeTest scripts

Tests/RunCMake/README.rst

@@ -86,17 +86,141 @@ To add a test:
 
    Note that trailing newlines will be stripped from actual and expected
    test output before matching against the stdout and stderr expressions.
-   The code in ``<case>-check.cmake`` may use variables
-
-   ``RunCMake_TEST_SOURCE_DIR``
-    Top of test source tree
-   ``RunCMake_TEST_BINARY_DIR``
-    Top of test binary tree
-
-   and an failure must store a message in ``RunCMake_TEST_FAILED``.
+   The code in ``<case>-check.cmake`` may use the `RunCMake Variables`_.
+   On failure the script must store a message in ``RunCMake_TEST_FAILED``.
    The check script may optionally set ``RunCMake_TEST_FAILURE_MESSAGE``
    with additional text to be included in the message if the test fails.
 
+RunCMake Commands
+=================
+
+A ``RunCMakeTest.cmake`` script, after ``include(RunCMake)``, may use
+the following commands.
+
+``run_cmake(<case>)``
+  Run CMake or another command and check expected results described by
+  ``<case>-{result,stdout,stderr}.txt`` and ``<case>-check.cmake``.
+  The command is executed by a call of the form::
+
+    execute_process(
+      COMMAND ${RunCMake_TEST_COMMAND} ${RunCMake_TEST_OPTIONS}
+      WORKING_DIRECTORY "${RunCMake_TEST_COMMAND_WORKING_DIRECTORY}"
+      [TIMEOUT "${RunCMake_TEST_TIMEOUT}"]
+      ...
+      )
+
+  Behavior may be customized by setting `RunCMake Variables`_ before
+  the call.
+
+``run_cmake_command(<case> <command> <args>...)``
+  Sets ``RunCMake_TEST_COMMAND`` to ``<command>;<args>...``
+  and calls ``run_cmake(<case>)``.
+
+  This is useful to run an arbitrary command.
+
+``run_cmake_script(<case> <args>...)``
+  Sets ``RunCMake_TEST_COMMAND`` to
+  ``${CMAKE_COMMAND};<args>...;-P;${RunCMake_SOURCE_DIR}/<case>.cmake``
+  and calls ``run_cmake(<case>)``.
+
+  This is useful to run CMake in script mode without configuring a project.
+
+``run_cmake_with_options(<case> <opts>...)``
+  Sets ``RunCMake_TEST_OPTIONS`` to ``<opts>...``
+  and calls ``run_cmake(<case>)``.
+
+``run_cmake_with_raw_args(<case> "<args>")``
+  Calls ``run_cmake(<case>)`` with the underlying ``execute_process()``
+  call extended with the content of ``<args>`` treated as literal source
+  code of CMake language command arguments::
+
+    execute_process(
+      COMMAND ${RunCMake_TEST_COMMAND} ${RunCMake_TEST_OPTIONS} <args>
+      ...
+      )
+
+  This is useful to pass arguments to the test command that cannot be
+  encoded in CMake language ``;``-separated lists.
+
+RunCMake Variables
+==================
+
+The behavior of `RunCMake Commands`_ such as ``run_cmake()`` may be
+customized by setting the following variables before a call.
+
+``RunCMake_GENERATOR``
+  CMake generator to use when configuring projects.
+  This provided to ``RunCMakeTest.cmake`` scripts automatically
+  when they are executed, based on the CMake generator used to
+  configure the test suite.
+
+  For some generators, additional variables are also provided:
+
+  ``RunCMake_GENERATOR_PLATFORM``
+    Specifies the ``CMAKE_GENERATOR_PLATFORM``.
+
+  ``RunCMake_GENERATOR_TOOLSET``
+    Specifies the ``CMAKE_GENERATOR_TOOLSET``.
+
+  ``RunCMake_GENERATOR_INSTANCE``
+    Specifies the ``CMAKE_GENERATOR_INSTANCE``.
+
+``RunCMake_GENERATOR_IS_MULTI_CONFIG``
+  Boolean value indicating whether ``${RunCMake_GENERATOR}`` is a
+  multi-config generator.
+  This provided to ``RunCMakeTest.cmake`` scripts automatically
+  when they are executed, based on the CMake generator used to
+  configure the test suite.
+
+``RunCMake_SOURCE_DIR``
+  Absolute path to the ``Tests/RunCMake/<Test>`` directory in
+  the CMake source tree.  This provided to ``RunCMakeTest.cmake``
+  scripts automatically when they are executed.
+
+``RunCMake_BINARY_DIR``
+  Absolute path to the ``Tests/RunCMake/<Test>`` directory in
+  the CMake binary tree.  This provided to ``RunCMakeTest.cmake``
+  scripts automatically when they are executed.
+
+``RunCMake_TEST_SOURCE_DIR``
+  Absolute path to the individual test case's source tree.
+  If not set, defaults to ``${RunCMake_SOURCE_DIR}``.
+
+``RunCMake_TEST_BINARY_DIR``
+  Absolute path to the individual test case's binary tree.
+  If not set, defaults to ``${RunCMake_BINARY_DIR}/<case>-build``.
+
+``RunCMake_TEST_NO_CLEAN``
+  Boolean value indicating whether ``run_cmake(<case>)`` should remove the
+  ``${RunCMake_TEST_BINARY_DIR}`` directory before running the test case.
+  If not set, or if set to a false value, the directory is removed.
+
+``RunCMake_TEST_COMMAND``
+  The command for ``run_cmake(<case>)`` to execute.
+  If not set, defaults to running CMake to generate a project::
+
+    ${CMAKE_COMMAND} ${RunCMake_TEST_SOURCE_DIR} \
+      -G ${RunCMake_GENERATOR} ... -DRunCMake_TEST=<case>
+
+``RunCMake_TEST_COMMAND_WORKING_DIRECTORY``
+  The working directory in which ``run_cmake(<case>)`` to execute its command.
+  If not set, defaults to ``${RunCMake_TEST_BINARY_DIR}``.
+
+``RunCMake_TEST_OPTIONS``
+  Additional command-line options for ``run_cmake(<case>)`` to pass to
+  CMake when configuring a project with a default ``RunCMake_TEST_COMMAND``.
+  If not set, defaults to empty.
+  If ``RunCMake_TEST_COMMAND`` is set, ``RunCMake_TEST_OPTIONS`` is forced
+  to empty.
+
+``RunCMake_TEST_OUTPUT_MERGE``
+  Boolean value indicating whether ``run_cmake(<case>)`` should redirect
+  the test process's ``stderr`` into its ``stdout``.
+
+``RunCMake_TEST_TIMEOUT``
+  Specify a timeout, in seconds, for ``run_cmake(<case>)`` to pass to its
+  underlying ``execute_process()`` call using the ``TIMEOUT`` option.
+
 Running a Test
 ==============