option
------

Provide an option that the user can modify.

There are two signatures, a simple boolean operation, and a full user option
signature.

.. code-block:: cmake

  option(<variable> "<help_text>" [value])

If no initial ``<value>`` is provided, boolean ``OFF`` is the default value.
If the variable is already set as a cache variable, the
:prop_cache:`HELPSTRING` will be set to ``<help_text>`` if the type is
``UNINITIALIZED``.  If ``<variable>`` is already set as a normal variable,
then the command does nothing (see policy :policy:`CMP0077`).

For boolean options that depend on the values of other options, see
the module help for :module:`CMakeDependentOption`.

In CMake project mode, a boolean cache variable is created with the option
value. In CMake script mode, a boolean variable is set with the option value.

.. code-block:: cmake

   option(<variable> "<help_text>" <value>
     [TYPE          <type>]
     [VALID_VALUES  <values>...]
     [ADVANCED]
     [DEFAULT]
     )

.. versionadded:: 3.31

With this signature, a cache variable is offered with the given ``<type>``
(defaulting to ``BOOL``).  If ``VALID_VALUES`` is specified, the ``TYPE`` must
be ``STRING``. Its value will be used to set the :prop_cache:`STRINGS`
property. If ``ADVANCED`` is specified, the cache variable is marked as
advanced. See :command:`mark_as_advanced`.  If ``DEFAULT`` is specified, the
:prop_cache:`DEFAULT` property will be set to ``<value>``. If the cache
variable does not already exist, the :prop_cache:`DEFAULTED` property will be
set to true.

If the variable is already set as a cache variable, the
:prop_cache:`HELPSTRING` property will be set to ``<help_text>`` and the
:prop_cache:`TYPE` property will be updated if the type is ``UNINITIALIZED``.
Additionally, the :prop_cache:`STRINGS` property will be set or unset based on
the ``VALID_VALUES`` argument, the :prop_cache:`ADVANCED` property will be set
based on the ``ADVANCED`` argument, and :prop_cache:`DEFAULT` will be updated
to ``<value>`` if ``DEFAULT`` is specified or unset otherwise.  If
``<variable>`` is already set as a normal variable, then the command does
nothing.
