Help: Clarify search order for resource spec file

Clarify the order in which --resource-spec-file, RESOURCE_SPEC_FILE,
and CTEST_RESOURCE_SPEC_FILE are searched, and add tests to
enforce this.

Fixes: #20914

Help/manual/ctest.1.rst

@@ -1410,9 +1410,16 @@ Resource Specification File
 
 The resource specification file is a JSON file which is passed to CTest, either
 on the :manual:`ctest(1)` command line as ``--resource-spec-file``, or as the
-``RESOURCE_SPEC_FILE`` argument of :command:`ctest_test`. The resource
-specification file must be a JSON object. All examples in this document assume
-the following resource specification file:
+``RESOURCE_SPEC_FILE`` argument of :command:`ctest_test`. If a dashboard script
+is used and ``RESOURCE_SPEC_FILE`` is not specified, the value of
+:variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script is used instead.
+If ``--resource-spec-file``, ``RESOURCE_SPEC_FILE``, and
+:variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script are not specified,
+the value of :variable:`CTEST_RESOURCE_SPEC_FILE` in the CMake build is used
+instead. If none of these are specified, no resource spec file is used.
+
+The resource specification file must be a JSON object. All examples in this
+document assume the following resource specification file:
 
 .. code-block:: json
 

Help/variable/CTEST_RESOURCE_SPEC_FILE.rst

@@ -3,3 +3,8 @@ CTEST_RESOURCE_SPEC_FILE
 
 Specify the CTest ``ResourceSpecFile`` setting in a :manual:`ctest(1)`
 dashboard client script.
+
+This can also be used to specify the resource spec file from a CMake build. If
+no ``RESOURCE_SPEC_FILE`` is passed to :command:`ctest_test`, and
+``CTEST_RESOURCE_SPEC_FILE`` is not specified in the dashboard script, the
+value of this variable from the build is used.

Tests/RunCMake/CTestResourceAllocation/RunCMakeTest.cmake

@@ -153,6 +153,7 @@ function(run_ctest_resource name parallel random extra)
   if(extra)
     run_ctest("${name}-ctest-s-res-variable" "-DCTEST_RESOURCE_ALLOC_ENABLED=1" "-DCTEST_RESOURCE_SPEC_SOURCE=VARIABLE" "-DCTRESALLOC_COMMAND=${CTRESALLOC_COMMAND}" "-DCTEST_PARALLEL=${parallel}" "-DCTEST_RANDOM=${random}")
     run_ctest("${name}-ctest-s-res-cache" "-DCTEST_RESOURCE_ALLOC_ENABLED=1" "-DCTEST_RESOURCE_SPEC_SOURCE=CACHE" "-DCTRESALLOC_COMMAND=${CTRESALLOC_COMMAND}" "-DCTEST_PARALLEL=${parallel}" "-DCTEST_RANDOM=${random}")
+    run_ctest("${name}-ctest-s-res-cmdline" "-DCTEST_RESOURCE_ALLOC_ENABLED=1" "-DCTEST_RESOURCE_SPEC_SOURCE=CMDLINE" "-DCTRESALLOC_COMMAND=${CTRESALLOC_COMMAND}" "-DCTEST_PARALLEL=${parallel}" "-DCTEST_RANDOM=${random}" --resource-spec-file "${RunCMake_SOURCE_DIR}/resspec.json")
   endif()
 endfunction()
 

Tests/RunCMake/CTestResourceAllocation/checkfree1-ctest-s-res-cmdline-check.cmake

@@ -0,0 +1 @@
+verify_ctest_resources()

Tests/RunCMake/CTestResourceAllocation/notenough1-ctest-s-res-cmdline-check.cmake

@@ -0,0 +1,3 @@
+if(EXISTS "${RunCMake_TEST_BINARY_DIR}/ctresalloc.log")
+  set(RunCMake_TEST_FAILED "ctresalloc.log should not exist")
+endif()

Tests/RunCMake/CTestResourceAllocation/notenough1-ctest-s-res-cmdline-result.txt

@@ -0,0 +1 @@
+(-1|255)

Tests/RunCMake/CTestResourceAllocation/notenough1-ctest-s-res-cmdline-stderr.txt

@@ -0,0 +1,14 @@
+^Insufficient resources for test Test1:
+
+  Test requested resources of type 'fluxcapacitors' in the following amounts:
+    200 slots
+  but only the following units were available:
+    'outatime': 121 slots
+
+Resource spec file:
+
+  [^
+]*/Tests/RunCMake/CTestResourceAllocation/resspec.json
+CMake Error at [^
+]*/Tests/RunCMake/CTestResourceAllocation/notenough1-ctest-s-res-cmdline/test\.cmake:[0-9]+ \(message\):
+  Tests did not pass$

Tests/RunCMake/CTestResourceAllocation/test.cmake.in

@@ -12,10 +12,15 @@ set(config_options
   "-DCTEST_RESOURCE_ALLOC_ENABLED=${CTEST_RESOURCE_ALLOC_ENABLED};-DCTRESALLOC_COMMAND=${CTRESALLOC_COMMAND}"
   )
 
-if(CTEST_RESOURCE_SPEC_SOURCE STREQUAL "ARG")
+if(CTEST_RESOURCE_SPEC_SOURCE STREQUAL "CMDLINE")
+  list(APPEND config_options "-DCTEST_RESOURCE_SPEC_FILE=@RunCMake_SOURCE_DIR@/noexist.json")
+elseif(CTEST_RESOURCE_SPEC_SOURCE STREQUAL "ARG")
   set(resspec RESOURCE_SPEC_FILE "@RunCMake_SOURCE_DIR@/resspec.json")
+  set(CTEST_RESOURCE_SPEC_FILE "@RunCMake_SOURCE_DIR@/noexist.json")
+  list(APPEND config_options "-DCTEST_RESOURCE_SPEC_FILE=@RunCMake_SOURCE_DIR@/noexist.json")
 elseif(CTEST_RESOURCE_SPEC_SOURCE STREQUAL "VARIABLE")
   set(CTEST_RESOURCE_SPEC_FILE "@RunCMake_SOURCE_DIR@/resspec.json")
+  list(APPEND config_options "-DCTEST_RESOURCE_SPEC_FILE=@RunCMake_SOURCE_DIR@/noexist.json")
 elseif(CTEST_RESOURCE_SPEC_SOURCE STREQUAL "CACHE")
   list(APPEND config_options "-DCTEST_RESOURCE_SPEC_FILE=@RunCMake_SOURCE_DIR@/resspec.json")
 endif()