Documentation on CTEST_RESOURCE_SPEC_FILE is incomplete

A new CTEST_RESOURCE_SPEC_FILE variable is being added in CMake 3.18. The current docs don’t adequately specify how this variable relates to the other two ways of controlling the resource spec file:

  • Providing a ctest --resource-spec-file command line option.
  • Passing a RESOURCE_SPEC_FILE argument to the ctest_test() command.

Even looking at the code, it isn’t clear to me how the CTEST_RESOURCE_SPEC_FILE is supposed to interact with those two methods. Which one applies when, if more than one method is given? I thought CTEST_RESOURCE_SPEC_FILE was essentially just providing a default for the RESOURCE_SPEC_FILE option to the ctest_test() command, but I also see it mentioned at the handler level (i.e. in cmCTestTestHandler). We should clarify the docs around this new variable for the 3.18 release.

CC: @kyle.edwards

Edit: In hindsight, this probably should have been created as an issue in CMake’s gitlab, but I started out thinking this was going to be asking for my own clarification only and would probably be more of a discussion. :wink:

Let’s move discussion to gitlab, see this issue:

https://gitlab.kitware.com/cmake/cmake/-/issues/20914