dict()

IXM adds a new previously unavailable data type to CMake, the dict() command set. A dict() is a simple associative array, much like those typically found in other programming and scripting languages (though noticably absent from CMake). Much of dict()’s interface was made to mimic that of list(), though some operations must be different, simply due to the nature of the data type.

Interface

Reading
dict(KEYS dict out-var)
dict(GET dict key out-var)
Serialization
dict(JSON dict INTO filename)
dict(SAVE dict INTO filename)
dict(LOAD dict FROM filename)
Modification
dict(INSERT dict key [STRING|APPEND|ASSIGN] value…)
dict(TRANSFORM dict ACTION [SELECTOR] [OUTPUT_VARIABLE output-variable])
dict(MERGE dict [STRING|APPEND|ASSIGN] <other-dict> [<otherdict> …])
dict(REMOVE dict key [key…])
dict(CLEAR dict)

Reading

dict(KEYS)

The dictionary type keeps track of all keys stored within a dict(). At times, it is necessary to iterate over all the keys and this allows us to get them as a list whenever possible.

dict(GET)

It would not make much sense to have a data type that stores values if we could not get those values back. However unlike list(), which permits extracting several indices from a value, dict(GET) des not. Any additional extraction of the value stored into out-var should be run through the list(GET) command.

Serialization

Unlike other data types in CMake, the dict() type has a special format for serializing to disk. The details of this format is discussed elsewhere. In addition to serializing to this custom format, it can also serialize to JSON. However, because of limitations with CMake, we cannot then quickly and effeciently deserialize JSON to a dict(). The dict() type keeps support for its custom format to help caching additional information.

dict(JSON)

Serializes dict into filename as JSON. If dict does not exist, an empty JSON object will be written out.

Signature

dict(JSON <dict> INTO <filename>)
INTO
The filename to serialize the dict into. If the given filename is not of the form filename.json, it will have the .json extension automatically appended. If filename is a relative path, it will be placed into CMAKE_CURRENT_BINARY_DIR/filename.json. If filename already exists, its contents will be overwritten.

dict(SAVE)

Serializes dict into filename. If dict does not exist, an empty file will be written out

Signature

dict(SAVE <dict> INTO <filename>)
INTO
The filename to serialize the dict to. If the given filename is not of the form {filename}.ixm, it will have the .ixm extension automatically appended. If the filename is a relative path, it will be placed into CMAKE_CURRENT_BINARY_DIR. If filename already exists, its data will be overwritten.

dict(LOAD)

Deserializes <filename> into dict. If dict does not exist, it will be created.

Signature

dict(LOAD <dict> FROM <filename>)
FROM
The filename to deserialize the dict from. If the given filename is not of the form <filename>.ixm, it will have the .ixm extension automatically appended before trying to read from the file. If filename is a relative path, it will be read from CMAKE_CURRENT_BINARY_DIR. If filename does not exist, no operation will occur.

Modification

dict(INSERT)

As its name implies, dict(INSERT) will insert values into dict for the given key. If dict or key do not yet exist, they will be created.

Signature

dict(INSERT <dict> <key> [STRING|APPEND|ASSIGN] <value>...)
STRING
All values will be concatenated into a single string before being added to the key. This is equivalent to the APPEND_STRING option from set_property.
APPEND
All values will be appended to the key. If the key does not exist, it will have the same behavior as ASSIGN.
ASSIGN
All values are assigned directly to the key. If the key does not exist, it will be created. If the key already exists, its contents will be overwritten.

dict(TRANSFORM)

Transforms the values stored in key by using the list(TRANSFORM) subcommand. If dict or key does not exist, no operation will occur and any variables named by OUTPUT_VARIABLE will not be defined.

OUTPUT_VARIABLE
After the operation completes, the result will be placed into output-variable. If this option is not present, the key will be modified in place.

Signature

dict(TRANSFORM <dict> <key> <ACTION> [<SELECTOR>] [OUTPUT_VARIABLE <output variable>])

dict(MERGE)

Takes all the keys and values in other-dict… and merges their values into dict. If dict does not exist, it will be created. Each action is more or less equivalent to the actions found in dict(INSERT).

Signature

dict(MERGE <dict> [STRING|APPEND|ASSIGN] <other-dict> [<other-dict>...])
STRING
All values for similar keys will be concatenated into a single string when placed into dict. This is equivalent to the APPEND_STRING option from set_property.
APPEND
All values for similar keys will be appended into a single list before being set into dict. Duplicates are not removed.
ASSIGN
Each <other-dict> given will assign its keys values in the order they are passed to dict(MERGE). In other words, if two <other-dict> share the same key, the second one passed will overwrite the values of the first one.

dict(REMOVE)

Given dict, remove all values stored in key. If neither dict, nor key exist, this command will do nothing.

dict(CLEAR)

Removes all keys and values from dict. This is semantically equivalent to:

dict(KEYS <dict> keys)
dict(REMOVE <dict> ${keys})