1variable_watch 2-------------- 3 4Watch the CMake variable for change. 5 6.. code-block:: cmake 7 8 variable_watch(<variable> [<command>]) 9 10If the specified ``<variable>`` changes and no ``<command>`` is given, 11a message will be printed to inform about the change. 12 13If ``<command>`` is given, this command will be executed instead. 14The command will receive the following arguments: 15``COMMAND(<variable> <access> <value> <current_list_file> <stack>)`` 16 17``<variable>`` 18 Name of the variable being accessed. 19 20``<access>`` 21 One of ``READ_ACCESS``, ``UNKNOWN_READ_ACCESS``, ``MODIFIED_ACCESS``, 22 ``UNKNOWN_MODIFIED_ACCESS``, or ``REMOVED_ACCESS``. The ``UNKNOWN_`` 23 values are only used when the variable has never been set. Once set, 24 they are never used again during the same CMake run, even if the 25 variable is later unset. 26 27``<value>`` 28 The value of the variable. On a modification, this is the new 29 (modified) value of the variable. On removal, the value is empty. 30 31``<current_list_file>`` 32 Full path to the file doing the access. 33 34``<stack>`` 35 List of absolute paths of all files currently on the stack of file 36 inclusion, with the bottom-most file first and the currently 37 processed file (that is, ``current_list_file``) last. 38 39Note that for some accesses such as :command:`list(APPEND)`, the watcher 40is executed twice, first with a read access and then with a write one. 41Also note that an :command:`if(DEFINED)` query on the variable does not 42register as an access and the watcher is not executed. 43 44Only non-cache variables can be watched using this command. Access to 45cache variables is never watched. However, the existence of a cache 46variable ``var`` causes accesses to the non-cache variable ``var`` to 47not use the ``UNKNOWN_`` prefix, even if a non-cache variable ``var`` 48has never existed. 49