mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-07 14:20:06 -06:00
Help: Convert signatures of list and set commands
Convert documentation of the `list` and `set` commands to use new `signature` directive. Use new `cref` role in the `list` introduction so that the subcommands there are links rather than just text. Turn references into `string` subcommands into actual links. Reformat some prose as definition lists.
This commit is contained in:
Matthew Woehlke
@@ -36,23 +36,25 @@ Synopsis
|
|||||||
Introduction
|
Introduction
|
||||||
^^^^^^^^^^^^
|
^^^^^^^^^^^^
|
||||||
|
|
||||||
The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``PREPEND``,
|
The list subcommands :cref:`APPEND`, :cref:`INSERT`, :cref:`FILTER`,
|
||||||
``POP_BACK``, ``POP_FRONT``, ``REMOVE_AT``, ``REMOVE_ITEM``,
|
:cref:`PREPEND`, :cref:`POP_BACK`, :cref:`POP_FRONT`, :cref:`REMOVE_AT`,
|
||||||
``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create
|
:cref:`REMOVE_ITEM`, :cref:`REMOVE_DUPLICATES`, :cref:`REVERSE` and
|
||||||
new values for the list within the current CMake variable scope. Similar to
|
:cref:`SORT` may create new values for the list within the current CMake
|
||||||
the :command:`set` command, the LIST command creates new variable values in
|
variable scope. Similar to the :command:`set` command, the ``list`` command
|
||||||
the current scope, even if the list itself is actually defined in a parent
|
creates new variable values in the current scope, even if the list itself is
|
||||||
scope. To propagate the results of these operations upwards, use
|
actually defined in a parent scope. To propagate the results of these
|
||||||
:command:`set` with ``PARENT_SCOPE``, :command:`set` with
|
operations upwards, use :command:`set` with ``PARENT_SCOPE``,
|
||||||
``CACHE INTERNAL``, or some other means of value propagation.
|
:command:`set` with ``CACHE INTERNAL``, or some other means of value
|
||||||
|
propagation.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
A list in cmake is a ``;`` separated group of strings. To create a
|
A list in cmake is a ``;`` separated group of strings. To create a
|
||||||
list the set command can be used. For example, ``set(var a b c d e)``
|
list, the :command:`set` command can be used. For example,
|
||||||
creates a list with ``a;b;c;d;e``, and ``set(var "a b c d e")`` creates a
|
``set(var a b c d e)`` creates a list with ``a;b;c;d;e``, and
|
||||||
string or a list with one item in it. (Note macro arguments are not
|
``set(var "a b c d e")`` creates a string or a list with one item in it.
|
||||||
variables, and therefore cannot be used in LIST commands.)
|
(Note that macro arguments are not variables, and therefore cannot be used
|
||||||
|
in ``LIST`` commands.)
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
@@ -66,76 +68,54 @@ scope. To propagate the results of these operations upwards, use
|
|||||||
Reading
|
Reading
|
||||||
^^^^^^^
|
^^^^^^^
|
||||||
|
|
||||||
.. _LENGTH:
|
.. signature::
|
||||||
|
|
||||||
.. code-block:: cmake
|
|
||||||
|
|
||||||
list(LENGTH <list> <output variable>)
|
list(LENGTH <list> <output variable>)
|
||||||
|
|
||||||
Returns the list's length.
|
Returns the list's length.
|
||||||
|
|
||||||
.. _GET:
|
|
||||||
|
|
||||||
.. code-block:: cmake
|
|
||||||
|
|
||||||
|
.. signature::
|
||||||
list(GET <list> <element index> [<element index> ...] <output variable>)
|
list(GET <list> <element index> [<element index> ...] <output variable>)
|
||||||
|
|
||||||
Returns the list of elements specified by indices from the list.
|
Returns the list of elements specified by indices from the list.
|
||||||
|
|
||||||
.. _JOIN:
|
.. signature:: list(JOIN <list> <glue> <output variable>)
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. versionadded:: 3.12
|
||||||
|
|
||||||
list(JOIN <list> <glue> <output variable>)
|
Returns a string joining all list's elements using the glue string.
|
||||||
|
To join multiple strings, which are not part of a list,
|
||||||
.. versionadded:: 3.12
|
use :command:`string(JOIN)`.
|
||||||
|
|
||||||
Returns a string joining all list's elements using the glue string.
|
|
||||||
To join multiple strings, which are not part of a list, use ``JOIN`` operator
|
|
||||||
from :command:`string` command.
|
|
||||||
|
|
||||||
.. _SUBLIST:
|
|
||||||
|
|
||||||
.. code-block:: cmake
|
|
||||||
|
|
||||||
|
.. signature::
|
||||||
list(SUBLIST <list> <begin> <length> <output variable>)
|
list(SUBLIST <list> <begin> <length> <output variable>)
|
||||||
|
|
||||||
.. versionadded:: 3.12
|
.. versionadded:: 3.12
|
||||||
|
|
||||||
Returns a sublist of the given list.
|
Returns a sublist of the given list.
|
||||||
If ``<length>`` is 0, an empty list will be returned.
|
If ``<length>`` is 0, an empty list will be returned.
|
||||||
If ``<length>`` is -1 or the list is smaller than ``<begin>+<length>`` then
|
If ``<length>`` is -1 or the list is smaller than ``<begin>+<length>`` then
|
||||||
the remaining elements of the list starting at ``<begin>`` will be returned.
|
the remaining elements of the list starting at ``<begin>`` will be returned.
|
||||||
|
|
||||||
Search
|
Search
|
||||||
^^^^^^
|
^^^^^^
|
||||||
|
|
||||||
.. _FIND:
|
.. signature::
|
||||||
|
|
||||||
.. code-block:: cmake
|
|
||||||
|
|
||||||
list(FIND <list> <value> <output variable>)
|
list(FIND <list> <value> <output variable>)
|
||||||
|
|
||||||
Returns the index of the element specified in the list or -1
|
Returns the index of the element specified in the list
|
||||||
if it wasn't found.
|
or ``-1`` if it wasn't found.
|
||||||
|
|
||||||
Modification
|
Modification
|
||||||
^^^^^^^^^^^^
|
^^^^^^^^^^^^
|
||||||
|
|
||||||
.. _APPEND:
|
.. signature::
|
||||||
|
|
||||||
.. code-block:: cmake
|
|
||||||
|
|
||||||
list(APPEND <list> [<element> ...])
|
list(APPEND <list> [<element> ...])
|
||||||
|
|
||||||
Appends elements to the list. If no variable named ``<list>`` exists in the
|
Appends elements to the list. If no variable named ``<list>`` exists in the
|
||||||
current scope its value is treated as empty and the elements are appended to
|
current scope its value is treated as empty and the elements are appended to
|
||||||
that empty list.
|
that empty list.
|
||||||
|
|
||||||
.. _FILTER:
|
|
||||||
|
|
||||||
.. code-block:: cmake
|
|
||||||
|
|
||||||
|
.. signature::
|
||||||
list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
|
list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
|
||||||
|
|
||||||
.. versionadded:: 3.6
|
.. versionadded:: 3.6
|
||||||
@@ -146,219 +126,205 @@ In ``REGEX`` mode, items will be matched against the given regular expression.
|
|||||||
For more information on regular expressions look under
|
For more information on regular expressions look under
|
||||||
:ref:`string(REGEX) <Regex Specification>`.
|
:ref:`string(REGEX) <Regex Specification>`.
|
||||||
|
|
||||||
.. _INSERT:
|
.. signature::
|
||||||
|
|
||||||
.. code-block:: cmake
|
|
||||||
|
|
||||||
list(INSERT <list> <element_index> <element> [<element> ...])
|
list(INSERT <list> <element_index> <element> [<element> ...])
|
||||||
|
|
||||||
Inserts elements to the list to the specified index. It is an
|
Inserts elements to the list to the specified index. It is an
|
||||||
error to specify an out-of-range index. Valid indexes are 0 to `N`
|
error to specify an out-of-range index. Valid indexes are 0 to `N`
|
||||||
where `N` is the length of the list, inclusive. An empty list
|
where `N` is the length of the list, inclusive. An empty list
|
||||||
has length 0. If no variable named ``<list>`` exists in the
|
has length 0. If no variable named ``<list>`` exists in the
|
||||||
current scope its value is treated as empty and the elements are
|
current scope its value is treated as empty and the elements are
|
||||||
inserted in that empty list.
|
inserted in that empty list.
|
||||||
|
|
||||||
.. _POP_BACK:
|
|
||||||
|
|
||||||
.. code-block:: cmake
|
|
||||||
|
|
||||||
|
.. signature::
|
||||||
list(POP_BACK <list> [<out-var>...])
|
list(POP_BACK <list> [<out-var>...])
|
||||||
|
|
||||||
.. versionadded:: 3.15
|
.. versionadded:: 3.15
|
||||||
|
|
||||||
If no variable name is given, removes exactly one element. Otherwise,
|
If no variable name is given, removes exactly one element. Otherwise,
|
||||||
with `N` variable names provided, assign the last `N` elements' values
|
with `N` variable names provided, assign the last `N` elements' values
|
||||||
to the given variables and then remove the last `N` values from
|
to the given variables and then remove the last `N` values from
|
||||||
``<list>``.
|
``<list>``.
|
||||||
|
|
||||||
.. _POP_FRONT:
|
|
||||||
|
|
||||||
.. code-block:: cmake
|
|
||||||
|
|
||||||
|
.. signature::
|
||||||
list(POP_FRONT <list> [<out-var>...])
|
list(POP_FRONT <list> [<out-var>...])
|
||||||
|
|
||||||
.. versionadded:: 3.15
|
.. versionadded:: 3.15
|
||||||
|
|
||||||
If no variable name is given, removes exactly one element. Otherwise,
|
If no variable name is given, removes exactly one element. Otherwise,
|
||||||
with `N` variable names provided, assign the first `N` elements' values
|
with `N` variable names provided, assign the first `N` elements' values
|
||||||
to the given variables and then remove the first `N` values from
|
to the given variables and then remove the first `N` values from
|
||||||
``<list>``.
|
``<list>``.
|
||||||
|
|
||||||
.. _PREPEND:
|
|
||||||
|
|
||||||
.. code-block:: cmake
|
|
||||||
|
|
||||||
|
.. signature::
|
||||||
list(PREPEND <list> [<element> ...])
|
list(PREPEND <list> [<element> ...])
|
||||||
|
|
||||||
.. versionadded:: 3.15
|
.. versionadded:: 3.15
|
||||||
|
|
||||||
Insert elements to the 0th position in the list. If no variable named
|
Insert elements to the 0th position in the list. If no variable named
|
||||||
``<list>`` exists in the current scope its value is treated as empty and
|
``<list>`` exists in the current scope its value is treated as empty and
|
||||||
the elements are prepended to that empty list.
|
the elements are prepended to that empty list.
|
||||||
|
|
||||||
.. _REMOVE_ITEM:
|
|
||||||
|
|
||||||
.. code-block:: cmake
|
|
||||||
|
|
||||||
|
.. signature::
|
||||||
list(REMOVE_ITEM <list> <value> [<value> ...])
|
list(REMOVE_ITEM <list> <value> [<value> ...])
|
||||||
|
|
||||||
Removes all instances of the given items from the list.
|
Removes all instances of the given items from the list.
|
||||||
|
|
||||||
.. _REMOVE_AT:
|
|
||||||
|
|
||||||
.. code-block:: cmake
|
|
||||||
|
|
||||||
|
.. signature::
|
||||||
list(REMOVE_AT <list> <index> [<index> ...])
|
list(REMOVE_AT <list> <index> [<index> ...])
|
||||||
|
|
||||||
Removes items at given indices from the list.
|
Removes items at given indices from the list.
|
||||||
|
|
||||||
.. _REMOVE_DUPLICATES:
|
|
||||||
|
|
||||||
.. code-block:: cmake
|
|
||||||
|
|
||||||
|
.. signature::
|
||||||
list(REMOVE_DUPLICATES <list>)
|
list(REMOVE_DUPLICATES <list>)
|
||||||
|
|
||||||
Removes duplicated items in the list. The relative order of items is preserved,
|
Removes duplicated items in the list. The relative order of items
|
||||||
but if duplicates are encountered, only the first instance is preserved.
|
is preserved, but if duplicates are encountered,
|
||||||
|
only the first instance is preserved.
|
||||||
.. _TRANSFORM:
|
|
||||||
|
|
||||||
.. code-block:: cmake
|
|
||||||
|
|
||||||
|
.. signature::
|
||||||
list(TRANSFORM <list> <ACTION> [<SELECTOR>]
|
list(TRANSFORM <list> <ACTION> [<SELECTOR>]
|
||||||
[OUTPUT_VARIABLE <output variable>])
|
[OUTPUT_VARIABLE <output variable>])
|
||||||
|
|
||||||
.. versionadded:: 3.12
|
.. versionadded:: 3.12
|
||||||
|
|
||||||
Transforms the list by applying an action to all or, by specifying a
|
Transforms the list by applying an action to all or, by specifying a
|
||||||
``<SELECTOR>``, to the selected elements of the list, storing the result
|
``<SELECTOR>``, to the selected elements of the list, storing the result
|
||||||
in-place or in the specified output variable.
|
in-place or in the specified output variable.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
The ``TRANSFORM`` sub-command does not change the number of elements in the
|
The ``TRANSFORM`` sub-command does not change the number of elements in the
|
||||||
list. If a ``<SELECTOR>`` is specified, only some elements will be changed,
|
list. If a ``<SELECTOR>`` is specified, only some elements will be changed,
|
||||||
the other ones will remain the same as before the transformation.
|
the other ones will remain the same as before the transformation.
|
||||||
|
|
||||||
``<ACTION>`` specifies the action to apply to the elements of the list.
|
``<ACTION>`` specifies the action to apply to the elements of the list.
|
||||||
The actions have exactly the same semantics as sub-commands of the
|
The actions have exactly the same semantics as sub-commands of the
|
||||||
:command:`string` command. ``<ACTION>`` must be one of the following:
|
:command:`string` command. ``<ACTION>`` must be one of the following:
|
||||||
|
|
||||||
``APPEND``, ``PREPEND``: Append, prepend specified value to each element of
|
:command:`APPEND <string(APPEND)>`, :command:`PREPEND <string(PREPEND)>`
|
||||||
the list.
|
Append, prepend specified value to each element of the list.
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. code-block:: cmake
|
||||||
|
|
||||||
list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
|
list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
|
||||||
|
|
||||||
``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower
|
:command:`TOUPPER <string(TOUPPER)>`, :command:`TOLOWER <string(TOLOWER)>`
|
||||||
characters.
|
Convert each element of the list to upper, lower characters.
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. code-block:: cmake
|
||||||
|
|
||||||
list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
|
list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
|
||||||
|
|
||||||
``STRIP``: Remove leading and trailing spaces from each element of the
|
:command:`STRIP <string(STRIP)>`
|
||||||
list.
|
Remove leading and trailing spaces from each element of the list.
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. code-block:: cmake
|
||||||
|
|
||||||
list(TRANSFORM <list> STRIP ...)
|
list(TRANSFORM <list> STRIP ...)
|
||||||
|
|
||||||
``GENEX_STRIP``: Strip any
|
:command:`GENEX_STRIP <string(GENEX_STRIP)>`
|
||||||
:manual:`generator expressions <cmake-generator-expressions(7)>` from each
|
Strip any
|
||||||
element of the list.
|
:manual:`generator expressions <cmake-generator-expressions(7)>`
|
||||||
|
from each element of the list.
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. code-block:: cmake
|
||||||
|
|
||||||
list(TRANSFORM <list> GENEX_STRIP ...)
|
list(TRANSFORM <list> GENEX_STRIP ...)
|
||||||
|
|
||||||
``REPLACE``: Match the regular expression as many times as possible and
|
:command:`REPLACE <string(REGEX REPLACE)>`:
|
||||||
substitute the replacement expression for the match for each element
|
Match the regular expression as many times as possible and substitute
|
||||||
of the list
|
the replacement expression for the match for each element of the list
|
||||||
(Same semantic as ``REGEX REPLACE`` from :command:`string` command).
|
(same semantic as :command:`string(REGEX REPLACE)`).
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. code-block:: cmake
|
||||||
|
|
||||||
list(TRANSFORM <list> REPLACE <regular_expression>
|
list(TRANSFORM <list> REPLACE <regular_expression>
|
||||||
<replace_expression> ...)
|
<replace_expression> ...)
|
||||||
|
|
||||||
``<SELECTOR>`` determines which elements of the list will be transformed.
|
``<SELECTOR>`` determines which elements of the list will be transformed.
|
||||||
Only one type of selector can be specified at a time. When given,
|
Only one type of selector can be specified at a time.
|
||||||
``<SELECTOR>`` must be one of the following:
|
When given, ``<SELECTOR>`` must be one of the following:
|
||||||
|
|
||||||
``AT``: Specify a list of indexes.
|
``AT``
|
||||||
|
Specify a list of indexes.
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. code-block:: cmake
|
||||||
|
|
||||||
list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
|
list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
|
||||||
|
|
||||||
``FOR``: Specify a range with, optionally, an increment used to iterate over
|
``FOR``
|
||||||
the range.
|
Specify a range with, optionally,
|
||||||
|
an increment used to iterate over the range.
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. code-block:: cmake
|
||||||
|
|
||||||
list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
|
list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
|
||||||
|
|
||||||
``REGEX``: Specify a regular expression. Only elements matching the regular
|
``REGEX``
|
||||||
expression will be transformed.
|
Specify a regular expression.
|
||||||
|
Only elements matching the regular expression will be transformed.
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. code-block:: cmake
|
||||||
|
|
||||||
list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
|
list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
|
||||||
|
|
||||||
|
|
||||||
Ordering
|
Ordering
|
||||||
^^^^^^^^
|
^^^^^^^^
|
||||||
|
|
||||||
.. _REVERSE:
|
.. signature::
|
||||||
|
|
||||||
.. code-block:: cmake
|
|
||||||
|
|
||||||
list(REVERSE <list>)
|
list(REVERSE <list>)
|
||||||
|
|
||||||
Reverses the contents of the list in-place.
|
Reverses the contents of the list in-place.
|
||||||
|
|
||||||
.. _SORT:
|
|
||||||
|
|
||||||
.. code-block:: cmake
|
|
||||||
|
|
||||||
|
.. signature::
|
||||||
list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
|
list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
|
||||||
|
|
||||||
Sorts the list in-place alphabetically.
|
Sorts the list in-place alphabetically.
|
||||||
|
|
||||||
.. versionadded:: 3.13
|
.. versionadded:: 3.13
|
||||||
Added the ``COMPARE``, ``CASE``, and ``ORDER`` options.
|
Added the ``COMPARE``, ``CASE``, and ``ORDER`` options.
|
||||||
|
|
||||||
.. versionadded:: 3.18
|
.. versionadded:: 3.18
|
||||||
Added the ``COMPARE NATURAL`` option.
|
Added the ``COMPARE NATURAL`` option.
|
||||||
|
|
||||||
Use the ``COMPARE`` keyword to select the comparison method for sorting.
|
Use the ``COMPARE`` keyword to select the comparison method for sorting.
|
||||||
The ``<compare>`` option should be one of:
|
The ``<compare>`` option should be one of:
|
||||||
|
|
||||||
* ``STRING``: Sorts a list of strings alphabetically. This is the
|
``STRING``
|
||||||
default behavior if the ``COMPARE`` option is not given.
|
Sorts a list of strings alphabetically.
|
||||||
* ``FILE_BASENAME``: Sorts a list of pathnames of files by their basenames.
|
This is the default behavior if the ``COMPARE`` option is not given.
|
||||||
* ``NATURAL``: Sorts a list of strings using natural order
|
|
||||||
(see ``strverscmp(3)`` manual), i.e. such that contiguous digits
|
|
||||||
are compared as whole numbers.
|
|
||||||
For example: the following list `10.0 1.1 2.1 8.0 2.0 3.1`
|
|
||||||
will be sorted as `1.1 2.0 2.1 3.1 8.0 10.0` if the ``NATURAL``
|
|
||||||
comparison is selected where it will be sorted as
|
|
||||||
`1.1 10.0 2.0 2.1 3.1 8.0` with the ``STRING`` comparison.
|
|
||||||
|
|
||||||
Use the ``CASE`` keyword to select a case sensitive or case insensitive
|
``FILE_BASENAME``
|
||||||
sort mode. The ``<case>`` option should be one of:
|
Sorts a list of pathnames of files by their basenames.
|
||||||
|
|
||||||
* ``SENSITIVE``: List items are sorted in a case-sensitive manner. This is
|
``NATURAL``
|
||||||
the default behavior if the ``CASE`` option is not given.
|
Sorts a list of strings using natural order
|
||||||
* ``INSENSITIVE``: List items are sorted case insensitively. The order of
|
(see ``strverscmp(3)`` manual), i.e. such that contiguous digits
|
||||||
items which differ only by upper/lowercase is not specified.
|
are compared as whole numbers.
|
||||||
|
For example: the following list `10.0 1.1 2.1 8.0 2.0 3.1`
|
||||||
|
will be sorted as `1.1 2.0 2.1 3.1 8.0 10.0` if the ``NATURAL``
|
||||||
|
comparison is selected where it will be sorted as
|
||||||
|
`1.1 10.0 2.0 2.1 3.1 8.0` with the ``STRING`` comparison.
|
||||||
|
|
||||||
To control the sort order, the ``ORDER`` keyword can be given.
|
Use the ``CASE`` keyword to select a case sensitive or case insensitive
|
||||||
The ``<order>`` option should be one of:
|
sort mode. The ``<case>`` option should be one of:
|
||||||
|
|
||||||
* ``ASCENDING``: Sorts the list in ascending order. This is the default
|
``SENSITIVE``
|
||||||
behavior when the ``ORDER`` option is not given.
|
List items are sorted in a case-sensitive manner.
|
||||||
* ``DESCENDING``: Sorts the list in descending order.
|
This is the default behavior if the ``CASE`` option is not given.
|
||||||
|
|
||||||
|
``INSENSITIVE``
|
||||||
|
List items are sorted case insensitively. The order of
|
||||||
|
items which differ only by upper/lowercase is not specified.
|
||||||
|
|
||||||
|
To control the sort order, the ``ORDER`` keyword can be given.
|
||||||
|
The ``<order>`` option should be one of:
|
||||||
|
|
||||||
|
``ASCENDING``
|
||||||
|
Sorts the list in ascending order.
|
||||||
|
This is the default behavior when the ``ORDER`` option is not given.
|
||||||
|
|
||||||
|
``DESCENDING``
|
||||||
|
Sorts the list in descending order.
|
||||||
|
|||||||
@@ -15,102 +15,107 @@ unset. See the :command:`unset` command to unset variables explicitly.
|
|||||||
Set Normal Variable
|
Set Normal Variable
|
||||||
^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. signature::
|
||||||
|
|
||||||
set(<variable> <value>... [PARENT_SCOPE])
|
set(<variable> <value>... [PARENT_SCOPE])
|
||||||
|
:target: normal
|
||||||
|
|
||||||
Sets the given ``<variable>`` in the current function or directory scope.
|
Sets the given ``<variable>`` in the current function or directory scope.
|
||||||
|
|
||||||
If the ``PARENT_SCOPE`` option is given the variable will be set in
|
If the ``PARENT_SCOPE`` option is given the variable will be set in
|
||||||
the scope above the current scope. Each new directory or :command:`function`
|
the scope above the current scope. Each new directory or :command:`function`
|
||||||
command creates a new scope. A scope can also be created with the
|
command creates a new scope. A scope can also be created with the
|
||||||
:command:`block` command. This command will set the value of a variable into
|
:command:`block` command. This command will set the value of a variable into
|
||||||
the parent directory, calling function or encompassing scope (whichever is
|
the parent directory, calling function or encompassing scope (whichever is
|
||||||
applicable to the case at hand). The previous state of the variable's value
|
applicable to the case at hand). The previous state of the variable's value
|
||||||
stays the same in the current scope (e.g., if it was undefined before, it is
|
stays the same in the current scope (e.g., if it was undefined before, it is
|
||||||
still undefined and if it had a value, it is still that value).
|
still undefined and if it had a value, it is still that value).
|
||||||
|
|
||||||
The :command:`block(PROPAGATE)` and :command:`return(PROPAGATE)` commands can
|
The :command:`block(PROPAGATE)` and :command:`return(PROPAGATE)` commands
|
||||||
be used as an alternate method to the :command:`set(PARENT_SCOPE)` and
|
can be used as an alternate method to the :command:`set(PARENT_SCOPE)`
|
||||||
:command:`unset(PARENT_SCOPE)` commands to update the parent scope.
|
and :command:`unset(PARENT_SCOPE)` commands to update the parent scope.
|
||||||
|
|
||||||
Set Cache Entry
|
Set Cache Entry
|
||||||
^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. signature::
|
||||||
|
|
||||||
set(<variable> <value>... CACHE <type> <docstring> [FORCE])
|
set(<variable> <value>... CACHE <type> <docstring> [FORCE])
|
||||||
|
:target: CACHE
|
||||||
|
|
||||||
Sets the given cache ``<variable>`` (cache entry). Since cache entries
|
Sets the given cache ``<variable>`` (cache entry). Since cache entries
|
||||||
are meant to provide user-settable values this does not overwrite
|
are meant to provide user-settable values this does not overwrite
|
||||||
existing cache entries by default. Use the ``FORCE`` option to
|
existing cache entries by default. Use the ``FORCE`` option to
|
||||||
overwrite existing entries.
|
overwrite existing entries.
|
||||||
|
|
||||||
The ``<type>`` must be specified as one of:
|
The ``<type>`` must be specified as one of:
|
||||||
|
|
||||||
``BOOL``
|
``BOOL``
|
||||||
Boolean ``ON/OFF`` value. :manual:`cmake-gui(1)` offers a checkbox.
|
Boolean ``ON/OFF`` value.
|
||||||
|
:manual:`cmake-gui(1)` offers a checkbox.
|
||||||
|
|
||||||
``FILEPATH``
|
``FILEPATH``
|
||||||
Path to a file on disk. :manual:`cmake-gui(1)` offers a file dialog.
|
Path to a file on disk.
|
||||||
|
:manual:`cmake-gui(1)` offers a file dialog.
|
||||||
|
|
||||||
``PATH``
|
``PATH``
|
||||||
Path to a directory on disk. :manual:`cmake-gui(1)` offers a file dialog.
|
Path to a directory on disk.
|
||||||
|
:manual:`cmake-gui(1)` offers a file dialog.
|
||||||
|
|
||||||
``STRING``
|
``STRING``
|
||||||
A line of text. :manual:`cmake-gui(1)` offers a text field or a
|
A line of text.
|
||||||
drop-down selection if the :prop_cache:`STRINGS` cache entry
|
:manual:`cmake-gui(1)` offers a text field or a drop-down selection
|
||||||
property is set.
|
if the :prop_cache:`STRINGS` cache entry property is set.
|
||||||
|
|
||||||
``INTERNAL``
|
``INTERNAL``
|
||||||
A line of text. :manual:`cmake-gui(1)` does not show internal entries.
|
A line of text.
|
||||||
They may be used to store variables persistently across runs.
|
:manual:`cmake-gui(1)` does not show internal entries.
|
||||||
Use of this type implies ``FORCE``.
|
They may be used to store variables persistently across runs.
|
||||||
|
Use of this type implies ``FORCE``.
|
||||||
|
|
||||||
The ``<docstring>`` must be specified as a line of text providing
|
The ``<docstring>`` must be specified as a line of text
|
||||||
a quick summary of the option for presentation to :manual:`cmake-gui(1)`
|
providing a quick summary of the option
|
||||||
users.
|
for presentation to :manual:`cmake-gui(1)` users.
|
||||||
|
|
||||||
If the cache entry does not exist prior to the call or the ``FORCE``
|
If the cache entry does not exist prior to the call or the ``FORCE``
|
||||||
option is given then the cache entry will be set to the given value.
|
option is given then the cache entry will be set to the given value.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
The content of the cache variable will not be directly accessible if a normal
|
The content of the cache variable will not be directly accessible
|
||||||
variable of the same name already exists (see :ref:`rules of variable
|
if a normal variable of the same name already exists
|
||||||
evaluation <CMake Language Variables>`). If policy :policy:`CMP0126` is set
|
(see :ref:`rules of variable evaluation <CMake Language Variables>`).
|
||||||
to ``OLD``, any normal variable binding in the current scope will be removed.
|
If policy :policy:`CMP0126` is set to ``OLD``, any normal variable
|
||||||
|
binding in the current scope will be removed.
|
||||||
|
|
||||||
It is possible for the cache entry to exist prior to the call but
|
It is possible for the cache entry to exist prior to the call but
|
||||||
have no type set if it was created on the :manual:`cmake(1)` command
|
have no type set if it was created on the :manual:`cmake(1)` command
|
||||||
line by a user through the :option:`-D\<var\>=\<value\> <cmake -D>` option without
|
line by a user through the :option:`-D\<var\>=\<value\> <cmake -D>` option
|
||||||
specifying a type. In this case the ``set`` command will add the
|
without specifying a type. In this case the ``set`` command will add the
|
||||||
type. Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH``
|
type. Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH``
|
||||||
and the ``<value>`` provided on the command line is a relative path,
|
and the ``<value>`` provided on the command line is a relative path,
|
||||||
then the ``set`` command will treat the path as relative to the
|
then the ``set`` command will treat the path as relative to the
|
||||||
current working directory and convert it to an absolute path.
|
current working directory and convert it to an absolute path.
|
||||||
|
|
||||||
Set Environment Variable
|
Set Environment Variable
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. signature::
|
||||||
|
|
||||||
set(ENV{<variable>} [<value>])
|
set(ENV{<variable>} [<value>])
|
||||||
|
:target: ENV
|
||||||
|
|
||||||
Sets an :manual:`Environment Variable <cmake-env-variables(7)>`
|
Sets an :manual:`Environment Variable <cmake-env-variables(7)>`
|
||||||
to the given value.
|
to the given value.
|
||||||
Subsequent calls of ``$ENV{<variable>}`` will return this new value.
|
Subsequent calls of ``$ENV{<variable>}`` will return this new value.
|
||||||
|
|
||||||
This command affects only the current CMake process, not the process
|
This command affects only the current CMake process, not the process
|
||||||
from which CMake was called, nor the system environment at large,
|
from which CMake was called, nor the system environment at large,
|
||||||
nor the environment of subsequent build or test processes.
|
nor the environment of subsequent build or test processes.
|
||||||
|
|
||||||
If no argument is given after ``ENV{<variable>}`` or if ``<value>`` is
|
If no argument is given after ``ENV{<variable>}`` or if ``<value>`` is
|
||||||
an empty string, then this command will clear any existing value of the
|
an empty string, then this command will clear any existing value of the
|
||||||
environment variable.
|
environment variable.
|
||||||
|
|
||||||
Arguments after ``<value>`` are ignored. If extra arguments are found,
|
Arguments after ``<value>`` are ignored. If extra arguments are found,
|
||||||
then an author warning is issued.
|
then an author warning is issued.
|
||||||
|
|
||||||
See Also
|
See Also
|
||||||
^^^^^^^^
|
^^^^^^^^
|
||||||
|
|||||||
Reference in New Issue
Block a user