Skip to content

Commit 95db8c5

Browse files
bradkingkwrobot
authored andcommitted
Merge topic 'variable_watch_docs'
bb15663 Help: Expand documentation of variable_watch() Acked-by: Kitware Robot <kwrobot@kitware.com> Merge-request: !4990
2 parents 9e2d480 + bb15663 commit 95db8c5

File tree

1 file changed

+36
-3
lines changed

1 file changed

+36
-3
lines changed

Help/command/variable_watch.rst

Lines changed: 36 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,42 @@ Watch the CMake variable for change.
77
88
variable_watch(<variable> [<command>])
99
10-
If the specified ``<variable>`` changes, a message will be printed
11-
to inform about the change.
10+
If the specified ``<variable>`` changes and no ``<command>`` is given,
11+
a message will be printed to inform about the change.
1212

13-
Additionally, if ``<command>`` is given, this command will be executed.
13+
If ``<command>`` is given, this command will be executed instead.
1414
The command will receive the following arguments:
1515
``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+
39+
Note that for some accesses such as :command:`list(APPEND)`, the watcher
40+
is executed twice, first with a read access and then with a write one.
41+
Also note that an :command:`if(DEFINED)` query on the variable does not
42+
register as an access and the watcher is not executed.
43+
44+
Only non-cache variables can be watched using this command. Access to
45+
cache variables is never watched. However, the existence of a cache
46+
variable ``var`` causes accesses to the non-cache variable ``var`` to
47+
not use the ``UNKNOWN_`` prefix, even if a non-cache variable ``var``
48+
has never existed.

0 commit comments

Comments
 (0)