From bb156638585fac300c0b2fe04c721144d93415ef Mon Sep 17 00:00:00 2001 From: Petr Kmoch Date: Wed, 8 Jul 2020 19:07:36 +0200 Subject: Help: Expand documentation of variable_watch() Document parameters and corner-case behaviour of variable_watch() command. --- Help/command/variable_watch.rst | 39 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/Help/command/variable_watch.rst b/Help/command/variable_watch.rst index ce69bcf..8293f5a 100644 --- a/Help/command/variable_watch.rst +++ b/Help/command/variable_watch.rst @@ -7,9 +7,42 @@ Watch the CMake variable for change. variable_watch( []) -If the specified ```` changes, a message will be printed -to inform about the change. +If the specified ```` changes and no ```` is given, +a message will be printed to inform about the change. -Additionally, if ```` is given, this command will be executed. +If ```` is given, this command will be executed instead. The command will receive the following arguments: ``COMMAND( )`` + +```` + Name of the variable being accessed. + +```` + 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. + +```` + The value of the variable. On a modification, this is the new + (modified) value of the variable. On removal, the value is empty. + +```` + Full path to the file doing the access. + +```` + 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. -- cgit v0.12