variable_watch — CMake 4.1.1 Documentation

# variable_watch

Watch the CMake variable for change.

    variable_watch(<variable> [<command>])

If the specified `<variable>` changes and no `<command>` is given, a message will be printed to inform about the change.

If `<command>` is given, this command will be executed instead. The command will receive the following arguments: `COMMAND(<variable> <access> <value> <current_list_file> <stack>)`

`<variable>`

  Name of the variable being accessed.

`<access>`

  One of `READ_ACCESS`, `UNKNOWN_READ_ACCESS`, `MODIFIED_ACCESS`, `UNKNOWN_MODIFIED_ACCESS`, or `REMOVED_ACCESS`. The `UNKNOWN_` values are only used when the variable has never been set. Once set, they are never used again during the same CMake run, even if the variable is later unset.

`<value>`

  The value of the variable. On a modification, this is the new (modified) value of the variable. On removal, the value is empty.

`<current_list_file>`

  Full path to the file doing the access.

`<stack>`

  List of absolute paths of all files currently on the stack of file inclusion, with the bottom-most file first and the currently processed file (that is, `current_list_file`) last.

Note that for some accesses such as `list(APPEND)`, the watcher is executed twice, first with a read access and then with a write one. Also note that an `if(DEFINED)` query on the variable does not register as an access and the watcher is not executed.

Only non-cache variables can be watched using this command. Access to cache variables is never watched. However, the existence of a cache variable `var` causes accesses to the non-cache variable `var` to not use the `UNKNOWN_` prefix, even if a non-cache variable `var` has never existed.