mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-05 21:31:08 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge topic 'variable_watch_docs'

Browse Source 
bb15663858 Help: Expand documentation of variable_watch()

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !4990
This commit is contained in:
Brad King
2020-07-10 10:46:42 +00:00
committed by Kitware Robot
parent 9e2d480a3f bb15663858
commit 95db8c5db5
1 changed files with 36 additions and 3 deletions
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.