diff options
| author | Ben Boeckel <ben.boeckel@kitware.com> | 2022-03-29 20:26:26 (GMT) |
|---|---|---|
| committer | Brad King <brad.king@kitware.com> | 2022-03-30 20:05:37 (GMT) |
| commit | 7a614977f9443146e8b423b6dc5a11a7c79862ce (patch) | |
| tree | 7bd6412cafc38c217d7476c31a6ddc459e95634b | |
| parent | 00677703d00f94702ef94d8dd07387c8405a3caf (diff) | |
| download | CMake-7a614977f9443146e8b423b6dc5a11a7c79862ce.zip CMake-7a614977f9443146e8b423b6dc5a11a7c79862ce.tar.gz CMake-7a614977f9443146e8b423b6dc5a11a7c79862ce.tar.bz2 | |
CMakeDependentOption: improve documentation
This makes it far clearer that `<depends>` is a list up front instead of
burying the lede because a list is generally "trivially true" in CMake[1].
Also clarify that `<force>` is only available as a local variable and if
queried outside of the "scope" of the `cmake_dependent_option` call,
will get the stored user cache value.
[1] The exception being when the last entry ends in `-NOTFOUND`.
Suggested-by: Rui Oliveira
| -rw-r--r-- | Modules/CMakeDependentOption.cmake | 19 |
1 files changed, 12 insertions, 7 deletions
diff --git a/Modules/CMakeDependentOption.cmake b/Modules/CMakeDependentOption.cmake index b7c478f..ac0e262 100644 --- a/Modules/CMakeDependentOption.cmake +++ b/Modules/CMakeDependentOption.cmake @@ -16,13 +16,18 @@ conditions are true. cmake_dependent_option(<option> "<help_text>" <value> <depends> <force>) - Makes ``<option>`` available to the user if ``<depends>`` is true. When - ``<option>`` is available, the given ``<help_text>`` and initial ``<value>`` - are used. If the ``<depends>`` condition is not true, ``<option>`` will not be - presented and will always have the value given by ``<force>``. Any value set by - the user is preserved for when the option is presented again. In case ``<depends>`` - is a :ref:`semicolon-separated list <CMake Language Lists>`, all elements must - be true in order to initialize ``<option>`` with ``<value>``. + Makes ``<option>`` available to the user if the + :ref:`semicolon-separated list <CMake Language Lists>` of conditions in + ``<depends>`` are all true. Otherwise, a local variable named ``<option>`` + is set to ``<force>``. + + When ``<option>`` is available, the given ``<help_text>`` and initial + ``<value>`` are used. Otherwise, any value set by the user is preserved for + when ``<depends>`` is satisfied in the future. + + Note that the ``<option>`` variable only has a value which satisfies the + ``<depends>`` condition within the scope of the caller because it is a local + variable. Example invocation: |