echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Help: Expand documentation of variable_watch()

Browse Source 
Document parameters and corner-case behaviour of variable_watch() command.
This commit is contained in:
Petr Kmoch 2020-07-08 19:07:36 +02:00
parent ee781ac59d
commit bb15663858
1 changed files with 36 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
Help/command/variable_watch.rst
View File

@ -7,9 +7,42 @@ Watch the CMake variable for change.
variable_watch(<variable> [<command>])
If the specified ``<variable>`` changes, a message will be printed
to inform about the change.
If the specified ``<variable>`` changes and no ``<command>`` is given,
a message will be printed to inform about the change.
Additionally, if ``<command>`` is given, this command will be executed.
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.