mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-01 11:22:21 -06:00
8b25e11fed
This module also works in script mode. This is a sync with the option() command which mentions how the variable behaves in project and script mode.
254 lines
7.8 KiB
CMake
254 lines
7.8 KiB
CMake
# 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()
|