cmake/Help/prop_test/RESOURCE_GROUPS.rst

RESOURCE_GROUPS
---------------

.. versionadded:: 3.16

Specify resources required by a test, grouped in a way that is meaningful to
the test.  See :ref:`resource allocation <ctest-resource-allocation>`
for more information on how this property integrates into the CTest resource
allocation feature.

The ``RESOURCE_GROUPS`` property is a :ref:`semicolon-separated list <CMake
Language Lists>` of group descriptions. Each entry consists of an optional
number of groups using the description followed by a series of resource
requirements for those groups. These requirements (and the number of groups)
are separated by commas. The resource requirements consist of the name of a
resource type, followed by a colon, followed by an unsigned integer
specifying the number of slots required on one resource of the given type.

The ``RESOURCE_GROUPS`` property tells CTest what resources a test expects
to use grouped in a way meaningful to the test.  The test itself must read
the :ref:`environment variables <ctest-resource-environment-variables>` to
determine which resources have been allocated to each group.  For example,
each group may correspond to a process the test will spawn when executed.

Consider the following example:

.. code-block:: cmake

  add_test(NAME MyTest COMMAND MyExe)
  set_property(TEST MyTest PROPERTY RESOURCE_GROUPS
    "2,gpus:2"
    "gpus:4,crypto_chips:2")

In this example, there are two group descriptions (implicitly separated by a
semicolon.) The content of the first description is ``2,gpus:2``. This
description specifies 2 groups, each of which requires 2 slots from a single
GPU. The content of the second description is ``gpus:4,crypto_chips:2``. This
description does not specify a group count, so a default of 1 is assumed.
This single group requires 4 slots from a single GPU and 2 slots from a
single cryptography chip. In total, 3 resource groups are specified for this
test, each with its own unique requirements.

Note that the number of slots following the resource type specifies slots from
a *single* instance of the resource. If the resource group can tolerate
receiving slots from different instances of the same resource, it can indicate
this by splitting the specification into multiple requirements of one slot. For
example:

.. code-block:: cmake

  add_test(NAME MyTest COMMAND MyExe)
  set_property(TEST MyTest PROPERTY RESOURCE_GROUPS
    "gpus:1,gpus:1,gpus:1,gpus:1")

In this case, the single resource group indicates that it needs four GPU slots,
all of which may come from separate GPUs (though they don't have to; CTest may
still assign slots from the same GPU.)

When CTest sets the :ref:`environment variables
<ctest-resource-environment-variables>` for a test, it assigns a group number
based on the group description, starting at 0 on the left and the number of
groups minus 1 on the right. For example, in the example above, the two
groups in the first description would have IDs of 0 and 1, and the single
group in the second description would have an ID of 2.

Both the ``RESOURCE_GROUPS`` and :prop_test:`RESOURCE_LOCK` properties serve
similar purposes, but they are distinct and orthogonal. Resources specified by
``RESOURCE_GROUPS`` do not affect :prop_test:`RESOURCE_LOCK`, and vice versa.
Whereas :prop_test:`RESOURCE_LOCK` is a simpler property that is used for
locking one global resource, ``RESOURCE_GROUPS`` is a more advanced property
that allows multiple tests to simultaneously use multiple resources of the
same type, specifying their requirements in a fine-grained manner.