# 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:

    include(CMakeDependentOption)

## Commands

This module provides the following command:

cmake_dependent_option

  Provides a boolean option that depends on a set of conditions:

      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 `cmake-gui(1)` or `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 semicolon-separated list of multiple conditions.

    - Added in version 3.22: A full Condition Syntax as used in an `if(<condition>)` clause. See 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:

`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:

`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:

    $ 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:

    $ 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:

    $ 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.

`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.

`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:

`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 `option()` command to provide a boolean option that the user can optionally select.