# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file LICENSE.rst or https://cmake.org/licensing for details.
#[=======================================================================[.rst:
CMakeDependentOption
--------------------
This module provides a command to define boolean options whose availability and
default values depend on specified conditions or other options. This helps
maintain a clean configuration interface by only displaying options that are
relevant to the current settings.
Load this module in CMake with:
.. code-block:: cmake
include(CMakeDependentOption)
Commands
^^^^^^^^
This module provides the following command:
.. command:: cmake_dependent_option
Provides a boolean option that depends on a set of conditions:
.. code-block:: cmake
cmake_dependent_option(<variable> <help> <value> <condition> <else-value>)
This command creates a boolean ``<variable>`` and makes it available to the
user in the GUI (such as :manual:`cmake-gui(1)` or :manual:`ccmake(1)`), if
a set of conditions evaluates to boolean true.
The arguments are:
``<variable>``
The name of a variable that stores the option value.
``<help>``
A brief description of the option. This string is typically a short line of
text and is displayed in the GUI.
``<value>``
Boolean value for the ``<variable>``, when ``<condition>`` evaluates to
boolean true.
``<condition>``
Specifies the conditions that determine whether ``<variable>`` is set and
visible in the GUI.
* If ``<condition>`` evaluates to boolean false, option is hidden from the
user in the GUI, and a local variable ``<variable>`` is set to
``<else-value>``.
* If ``<condition>`` evaluates to boolean true, a boolean cache variable
named ``<variable>`` is created with default ``<value>``, and option is
shown in the GUI, allowing the user to enable or disable it.
* If ``<condition>`` later evaluates to boolean false (on consecutive
configuration run), option is hidden from the user in the GUI and the
``<variable>`` type is changed to an internal cache variable. In that
case a local variable of the same name is set to ``<else-value>``.
* If ``<condition>`` becomes true again in consecutive configuration runs,
the user's previously set value is preserved.
The ``<condition>`` argument can be:
* A single condition (such as a variable name).
* A :ref:`semicolon-separated list <CMake Language Lists>` of multiple
conditions.
* .. versionadded:: 3.22
A full :ref:`Condition Syntax` as used in an ``if(<condition>)`` clause.
See policy :policy:`CMP0127`. This enables using entire condition
syntax (such as grouping conditions with parens and similar).
``<else-value>``
The value assigned to a local variable named ``<variable>``, when
``<condition>`` evaluates to boolean false.
In CMake project mode, boolean cache variables are created as explained
above. In CMake script mode, boolean variables are set instead.
Examples
^^^^^^^^
Example: Basic Usage
""""""""""""""""""""
Using this module in a project to conditionally set an option:
.. code-block:: cmake
:caption: ``CMakeLists.txt``
include(CMakeDependentOption)
cmake_dependent_option(USE_SSL_GNUTLS "Use GnuTLS for SSL" ON USE_SSL OFF)
Example: Enabling/Disabling Dependent Option
""""""""""""""""""""""""""""""""""""""""""""
Extending the previous example, this demonstrates how the module allows
user-configurable options based on a condition during the configuration phase:
.. code-block:: cmake
:caption: ``CMakeLists.txt``
include(CMakeDependentOption)
option(USE_SSL "Enable SSL in the project" OFF)
cmake_dependent_option(USE_SSL_GNUTLS "Use GnuTLS for SSL" ON USE_SSL OFF)
message(STATUS "USE_SSL: ${USE_SSL}")
message(STATUS "USE_SSL_GNUTLS: ${USE_SSL_GNUTLS}")
On the first configuration run, a boolean cache variable ``USE_SSL`` is set to
OFF, and a local variable ``USE_SSL_GNUTLS`` is set to OFF:
.. code-block:: console
$ cmake -B build-dir
-- USE_SSL: OFF
-- USE_SSL_GNUTLS: OFF
Running CMake with ``USE_SSL=ON`` sets both ``USE_SSL`` and ``USE_SSL_GNUTLS``
boolean cache variables to ON:
.. code-block:: console
$ cmake -B build-dir -D USE_SSL=ON
-- USE_SSL: ON
-- USE_SSL_GNUTLS: ON
On a subsequent configuration run with ``USE_SSL=OFF``, ``USE_SSL_GNUTLS``
follows suit. However, its value is preserved in the internal cache while being
overridden locally:
.. code-block:: console
$ cmake -B build-dir -D USE_SSL=OFF
-- USE_SSL: OFF
-- USE_SSL_GNUTLS: OFF
Example: Semicolon-separated List of Conditions
"""""""""""""""""""""""""""""""""""""""""""""""
The ``<condition>`` argument can also be a semicolon-separated list of
conditions. In the following example, if the variable ``USE_BAR`` is ON and
variable ``USE_ZOT`` is OFF, the option ``USE_FOO`` is available and defaults to
ON. Otherwise, ``USE_FOO`` is set to OFF and hidden from the user.
If the values of ``USE_BAR`` or ``USE_ZOT`` change in the future configuration
runs, the previous value of ``USE_FOO`` is preserved so that when it becomes
available again, it retains its last set value.
.. code-block:: cmake
:caption: ``CMakeLists.txt``
include(CMakeDependentOption)
cmake_dependent_option(USE_FOO "Use Foo" ON "USE_BAR;NOT USE_ZOT" OFF)
Example: Full Condition Syntax
""""""""""""""""""""""""""""""
As of CMake 3.22, ``cmake_dependent_option()`` supports full condition syntax.
In fhe following example, if the condition evaluates to true, the option
``USE_FOO`` is available and set to ON. Otherwise, it is set to OFF and hidden
in the GUI. The value of ``USE_FOO`` is preserved across configuration runs,
similar to the previous example.
.. code-block:: cmake
:caption: ``CMakeLists.txt``
include(CMakeDependentOption)
cmake_dependent_option(USE_FOO "Use Foo" ON "USE_A AND (USE_B OR USE_C)" OFF)
Another example demonstrates how an option can be conditionally available based
on the target system:
.. code-block:: cmake
:caption: ``CMakeLists.txt``
include(CMakeDependentOption)
cmake_dependent_option(
ENABLE_FOO
"Enable feature Foo (this option is available when building for Windows)"
ON
[[CMAKE_SYSTEM_NAME STREQUAL "Windows"]]
OFF
)
See Also
^^^^^^^^
* The :command:`option` command to provide a boolean option that the user can
optionally select.
#]=======================================================================]
macro(CMAKE_DEPENDENT_OPTION option doc default depends force)
cmake_policy(GET CMP0127 _CDO_CMP0127
PARENT_SCOPE # undocumented, do not use outside of CMake
)
if(${option}_ISSET MATCHES "^${option}_ISSET$")
set(${option}_AVAILABLE 1)
if("x${_CDO_CMP0127}x" STREQUAL "xNEWx")
foreach(d ${depends})
cmake_language(EVAL CODE "
if (${d})
else()
set(${option}_AVAILABLE 0)
endif()"
)
endforeach()
else()
foreach(d ${depends})
string(REGEX REPLACE " +" ";" CMAKE_DEPENDENT_OPTION_DEP "${d}")
if(${CMAKE_DEPENDENT_OPTION_DEP})
else()
set(${option}_AVAILABLE 0)
endif()
endforeach()
endif()
if(${option}_AVAILABLE)
option(${option} "${doc}" "${default}")
set(${option} "${${option}}" CACHE BOOL "${doc}" FORCE)
else()
if(${option} MATCHES "^${option}$")
else()
set(${option} "${${option}}" CACHE INTERNAL "${doc}")
endif()
set(${option} ${force})
endif()
else()
set(${option} "${${option}_ISSET}")
endif()
if("x${_CDO_CMP0127}x" STREQUAL "xx" AND "x${depends}x" MATCHES "[^A-Za-z0-9_.; ]")
cmake_policy(GET_WARNING CMP0127 _CDO_CMP0127_WARNING)
message(AUTHOR_WARNING "${_CDO_CMP0127_WARNING}")
endif()
unset(_CDO_CMP0127)
endmacro()
