variable_watch
--------------

Watch the CMake variable for change.

.. code-block:: cmake

  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 :command:`list(APPEND)`, the watcher
is executed twice, first with a read access and then with a write one.
Also note that an :command:`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.