1RESOURCE_GROUPS 2--------------- 3 4.. versionadded:: 3.16 5 6Specify resources required by a test, grouped in a way that is meaningful to 7the test. See :ref:`resource allocation <ctest-resource-allocation>` 8for more information on how this property integrates into the CTest resource 9allocation feature. 10 11The ``RESOURCE_GROUPS`` property is a :ref:`semicolon-separated list <CMake 12Language Lists>` of group descriptions. Each entry consists of an optional 13number of groups using the description followed by a series of resource 14requirements for those groups. These requirements (and the number of groups) 15are separated by commas. The resource requirements consist of the name of a 16resource type, followed by a colon, followed by an unsigned integer 17specifying the number of slots required on one resource of the given type. 18 19The ``RESOURCE_GROUPS`` property tells CTest what resources a test expects 20to use grouped in a way meaningful to the test. The test itself must read 21the :ref:`environment variables <ctest-resource-environment-variables>` to 22determine which resources have been allocated to each group. For example, 23each group may correspond to a process the test will spawn when executed. 24 25Consider the following example: 26 27.. code-block:: cmake 28 29 add_test(NAME MyTest COMMAND MyExe) 30 set_property(TEST MyTest PROPERTY RESOURCE_GROUPS 31 "2,gpus:2" 32 "gpus:4,crypto_chips:2") 33 34In this example, there are two group descriptions (implicitly separated by a 35semicolon.) The content of the first description is ``2,gpus:2``. This 36description specifies 2 groups, each of which requires 2 slots from a single 37GPU. The content of the second description is ``gpus:4,crypto_chips:2``. This 38description does not specify a group count, so a default of 1 is assumed. 39This single group requires 4 slots from a single GPU and 2 slots from a 40single cryptography chip. In total, 3 resource groups are specified for this 41test, each with its own unique requirements. 42 43Note that the number of slots following the resource type specifies slots from 44a *single* instance of the resource. If the resource group can tolerate 45receiving slots from different instances of the same resource, it can indicate 46this by splitting the specification into multiple requirements of one slot. For 47example: 48 49.. code-block:: cmake 50 51 add_test(NAME MyTest COMMAND MyExe) 52 set_property(TEST MyTest PROPERTY RESOURCE_GROUPS 53 "gpus:1,gpus:1,gpus:1,gpus:1") 54 55In this case, the single resource group indicates that it needs four GPU slots, 56all of which may come from separate GPUs (though they don't have to; CTest may 57still assign slots from the same GPU.) 58 59When CTest sets the :ref:`environment variables 60<ctest-resource-environment-variables>` for a test, it assigns a group number 61based on the group description, starting at 0 on the left and the number of 62groups minus 1 on the right. For example, in the example above, the two 63groups in the first description would have IDs of 0 and 1, and the single 64group in the second description would have an ID of 2. 65 66Both the ``RESOURCE_GROUPS`` and :prop_test:`RESOURCE_LOCK` properties serve 67similar purposes, but they are distinct and orthogonal. Resources specified by 68``RESOURCE_GROUPS`` do not affect :prop_test:`RESOURCE_LOCK`, and vice versa. 69Whereas :prop_test:`RESOURCE_LOCK` is a simpler property that is used for 70locking one global resource, ``RESOURCE_GROUPS`` is a more advanced property 71that allows multiple tests to simultaneously use multiple resources of the 72same type, specifying their requirements in a fine-grained manner. 73