@@ -7,9 +7,42 @@ Watch the CMake variable for change.
7
7
8
8
variable_watch(<variable> [<command>])
9
9
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.
12
12
13
- Additionally, if ``<command> `` is given, this command will be executed.
13
+ If ``<command> `` is given, this command will be executed instead .
14
14
The command will receive the following arguments:
15
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
+
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