RESOURCE_GROUPS

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

The RESOURCE_GROUPS property is a semicolon-separated list 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 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:

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.

When CTest sets the 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 RESOURCE_LOCK properties serve similar purposes, but they are distinct and orthogonal. Resources specified by RESOURCE_GROUPS do not affect RESOURCE_LOCK, and vice versa. Whereas 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.