mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-06 13:51:33 -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
|
||||
^^^^^^^^^^^^
|
||||
|
||||
The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``PREPEND``,
|
||||
``POP_BACK``, ``POP_FRONT``, ``REMOVE_AT``, ``REMOVE_ITEM``,
|
||||
``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create
|
||||
new values for the list within the current CMake variable scope. Similar to
|
||||
the :command:`set` command, the LIST command creates new variable values in
|
||||
the current scope, even if the list itself is actually defined in a parent
|
||||
scope. To propagate the results of these operations upwards, use
|
||||
:command:`set` with ``PARENT_SCOPE``, :command:`set` with
|
||||
``CACHE INTERNAL``, or some other means of value propagation.
|
||||
The list subcommands :cref:`APPEND`, :cref:`INSERT`, :cref:`FILTER`,
|
||||
:cref:`PREPEND`, :cref:`POP_BACK`, :cref:`POP_FRONT`, :cref:`REMOVE_AT`,
|
||||
:cref:`REMOVE_ITEM`, :cref:`REMOVE_DUPLICATES`, :cref:`REVERSE` and
|
||||
:cref:`SORT` may create new values for the list within the current CMake
|
||||
variable scope. Similar to the :command:`set` command, the ``list`` command
|
||||
creates new variable values in the current scope, even if the list itself is
|
||||
actually defined in a parent scope. To propagate the results of these
|
||||
operations upwards, use :command:`set` with ``PARENT_SCOPE``,
|
||||
:command:`set` with ``CACHE INTERNAL``, or some other means of value
|
||||
propagation.
|
||||
|
||||
.. note::
|
||||
|
||||
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)``
|
||||
creates a list with ``a;b;c;d;e``, and ``set(var "a b c d e")`` creates a
|
||||
string or a list with one item in it. (Note macro arguments are not
|
||||
variables, and therefore cannot be used in LIST commands.)
|
||||
list, the :command:`set` command can be used. For example,
|
||||
``set(var a b c d e)`` creates a list with ``a;b;c;d;e``, and
|
||||
``set(var "a b c d e")`` creates a string or a list with one item in it.
|
||||
(Note that macro arguments are not variables, and therefore cannot be used
|
||||
in ``LIST`` commands.)
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -66,76 +68,54 @@ scope. To propagate the results of these operations upwards, use
|
||||
Reading
|
||||
^^^^^^^
|
||||
|
||||
.. _LENGTH:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
.. signature::
|
||||
list(LENGTH <list> <output variable>)
|
||||
|
||||
Returns the list's length.
|
||||
|
||||
.. _GET:
|
||||
|
||||
.. code-block:: cmake
|
||||
Returns the list's length.
|
||||
|
||||
.. signature::
|
||||
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>)
|
||||
|
||||
.. versionadded:: 3.12
|
||||
|
||||
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
|
||||
Returns a string joining all list's elements using the glue string.
|
||||
To join multiple strings, which are not part of a list,
|
||||
use :command:`string(JOIN)`.
|
||||
|
||||
.. signature::
|
||||
list(SUBLIST <list> <begin> <length> <output variable>)
|
||||
|
||||
.. versionadded:: 3.12
|
||||
.. versionadded:: 3.12
|
||||
|
||||
Returns a sublist of the given list.
|
||||
If ``<length>`` is 0, an empty list will be returned.
|
||||
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.
|
||||
Returns a sublist of the given list.
|
||||
If ``<length>`` is 0, an empty list will be returned.
|
||||
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.
|
||||
|
||||
Search
|
||||
^^^^^^
|
||||
|
||||
.. _FIND:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
.. signature::
|
||||
list(FIND <list> <value> <output variable>)
|
||||
|
||||
Returns the index of the element specified in the list or -1
|
||||
if it wasn't found.
|
||||
Returns the index of the element specified in the list
|
||||
or ``-1`` if it wasn't found.
|
||||
|
||||
Modification
|
||||
^^^^^^^^^^^^
|
||||
|
||||
.. _APPEND:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
.. signature::
|
||||
list(APPEND <list> [<element> ...])
|
||||
|
||||
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
|
||||
that empty list.
|
||||
|
||||
.. _FILTER:
|
||||
|
||||
.. code-block:: cmake
|
||||
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
|
||||
that empty list.
|
||||
|
||||
.. signature::
|
||||
list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
|
||||
|
||||
.. 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
|
||||
:ref:`string(REGEX) <Regex Specification>`.
|
||||
|
||||
.. _INSERT:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
.. signature::
|
||||
list(INSERT <list> <element_index> <element> [<element> ...])
|
||||
|
||||
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`
|
||||
where `N` is the length of the list, inclusive. An empty list
|
||||
has length 0. If no variable named ``<list>`` exists in the
|
||||
current scope its value is treated as empty and the elements are
|
||||
inserted in that empty list.
|
||||
|
||||
.. _POP_BACK:
|
||||
|
||||
.. code-block:: cmake
|
||||
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`
|
||||
where `N` is the length of the list, inclusive. An empty list
|
||||
has length 0. If no variable named ``<list>`` exists in the
|
||||
current scope its value is treated as empty and the elements are
|
||||
inserted in that empty list.
|
||||
|
||||
.. signature::
|
||||
list(POP_BACK <list> [<out-var>...])
|
||||
|
||||
.. versionadded:: 3.15
|
||||
.. versionadded:: 3.15
|
||||
|
||||
If no variable name is given, removes exactly one element. Otherwise,
|
||||
with `N` variable names provided, assign the last `N` elements' values
|
||||
to the given variables and then remove the last `N` values from
|
||||
``<list>``.
|
||||
|
||||
.. _POP_FRONT:
|
||||
|
||||
.. code-block:: cmake
|
||||
If no variable name is given, removes exactly one element. Otherwise,
|
||||
with `N` variable names provided, assign the last `N` elements' values
|
||||
to the given variables and then remove the last `N` values from
|
||||
``<list>``.
|
||||
|
||||
.. signature::
|
||||
list(POP_FRONT <list> [<out-var>...])
|
||||
|
||||
.. versionadded:: 3.15
|
||||
.. versionadded:: 3.15
|
||||
|
||||
If no variable name is given, removes exactly one element. Otherwise,
|
||||
with `N` variable names provided, assign the first `N` elements' values
|
||||
to the given variables and then remove the first `N` values from
|
||||
``<list>``.
|
||||
|
||||
.. _PREPEND:
|
||||
|
||||
.. code-block:: cmake
|
||||
If no variable name is given, removes exactly one element. Otherwise,
|
||||
with `N` variable names provided, assign the first `N` elements' values
|
||||
to the given variables and then remove the first `N` values from
|
||||
``<list>``.
|
||||
|
||||
.. signature::
|
||||
list(PREPEND <list> [<element> ...])
|
||||
|
||||
.. versionadded:: 3.15
|
||||
.. versionadded:: 3.15
|
||||
|
||||
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
|
||||
the elements are prepended to that empty list.
|
||||
|
||||
.. _REMOVE_ITEM:
|
||||
|
||||
.. code-block:: cmake
|
||||
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
|
||||
the elements are prepended to that empty list.
|
||||
|
||||
.. signature::
|
||||
list(REMOVE_ITEM <list> <value> [<value> ...])
|
||||
|
||||
Removes all instances of the given items from the list.
|
||||
|
||||
.. _REMOVE_AT:
|
||||
|
||||
.. code-block:: cmake
|
||||
Removes all instances of the given items from the list.
|
||||
|
||||
.. signature::
|
||||
list(REMOVE_AT <list> <index> [<index> ...])
|
||||
|
||||
Removes items at given indices from the list.
|
||||
|
||||
.. _REMOVE_DUPLICATES:
|
||||
|
||||
.. code-block:: cmake
|
||||
Removes items at given indices from the list.
|
||||
|
||||
.. signature::
|
||||
list(REMOVE_DUPLICATES <list>)
|
||||
|
||||
Removes duplicated items in the list. The relative order of items is preserved,
|
||||
but if duplicates are encountered, only the first instance is preserved.
|
||||
|
||||
.. _TRANSFORM:
|
||||
|
||||
.. code-block:: cmake
|
||||
Removes duplicated items in the list. The relative order of items
|
||||
is preserved, but if duplicates are encountered,
|
||||
only the first instance is preserved.
|
||||
|
||||
.. signature::
|
||||
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
|
||||
``<SELECTOR>``, to the selected elements of the list, storing the result
|
||||
in-place or in the specified output variable.
|
||||
Transforms the list by applying an action to all or, by specifying a
|
||||
``<SELECTOR>``, to the selected elements of the list, storing the result
|
||||
in-place or in the specified output variable.
|
||||
|
||||
.. note::
|
||||
.. note::
|
||||
|
||||
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,
|
||||
the other ones will remain the same as before the transformation.
|
||||
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,
|
||||
the other ones will remain the same as before the transformation.
|
||||
|
||||
``<ACTION>`` specifies the action to apply to the elements of the list.
|
||||
The actions have exactly the same semantics as sub-commands of the
|
||||
:command:`string` command. ``<ACTION>`` must be one of the following:
|
||||
``<ACTION>`` specifies the action to apply to the elements of the list.
|
||||
The actions have exactly the same semantics as sub-commands of the
|
||||
:command:`string` command. ``<ACTION>`` must be one of the following:
|
||||
|
||||
``APPEND``, ``PREPEND``: Append, prepend specified value to each element of
|
||||
the list.
|
||||
:command:`APPEND <string(APPEND)>`, :command:`PREPEND <string(PREPEND)>`
|
||||
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
|
||||
characters.
|
||||
:command:`TOUPPER <string(TOUPPER)>`, :command:`TOLOWER <string(TOLOWER)>`
|
||||
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
|
||||
list.
|
||||
:command:`STRIP <string(STRIP)>`
|
||||
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
|
||||
:manual:`generator expressions <cmake-generator-expressions(7)>` from each
|
||||
element of the list.
|
||||
:command:`GENEX_STRIP <string(GENEX_STRIP)>`
|
||||
Strip any
|
||||
: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
|
||||
substitute the replacement expression for the match for each element
|
||||
of the list
|
||||
(Same semantic as ``REGEX REPLACE`` from :command:`string` command).
|
||||
:command:`REPLACE <string(REGEX REPLACE)>`:
|
||||
Match the regular expression as many times as possible and substitute
|
||||
the replacement expression for the match for each element of the list
|
||||
(same semantic as :command:`string(REGEX REPLACE)`).
|
||||
|
||||
.. code-block:: cmake
|
||||
.. code-block:: cmake
|
||||
|
||||
list(TRANSFORM <list> REPLACE <regular_expression>
|
||||
<replace_expression> ...)
|
||||
list(TRANSFORM <list> REPLACE <regular_expression>
|
||||
<replace_expression> ...)
|
||||
|
||||
``<SELECTOR>`` determines which elements of the list will be transformed.
|
||||
Only one type of selector can be specified at a time. When given,
|
||||
``<SELECTOR>`` must be one of the following:
|
||||
``<SELECTOR>`` determines which elements of the list will be transformed.
|
||||
Only one type of selector can be specified at a time.
|
||||
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
|
||||
the range.
|
||||
``FOR``
|
||||
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
|
||||
expression will be transformed.
|
||||
``REGEX``
|
||||
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
|
||||
^^^^^^^^
|
||||
|
||||
.. _REVERSE:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
.. signature::
|
||||
list(REVERSE <list>)
|
||||
|
||||
Reverses the contents of the list in-place.
|
||||
|
||||
.. _SORT:
|
||||
|
||||
.. code-block:: cmake
|
||||
Reverses the contents of the list in-place.
|
||||
|
||||
.. signature::
|
||||
list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
|
||||
|
||||
Sorts the list in-place alphabetically.
|
||||
Sorts the list in-place alphabetically.
|
||||
|
||||
.. versionadded:: 3.13
|
||||
Added the ``COMPARE``, ``CASE``, and ``ORDER`` options.
|
||||
.. versionadded:: 3.13
|
||||
Added the ``COMPARE``, ``CASE``, and ``ORDER`` options.
|
||||
|
||||
.. versionadded:: 3.18
|
||||
Added the ``COMPARE NATURAL`` option.
|
||||
.. versionadded:: 3.18
|
||||
Added the ``COMPARE NATURAL`` option.
|
||||
|
||||
Use the ``COMPARE`` keyword to select the comparison method for sorting.
|
||||
The ``<compare>`` option should be one of:
|
||||
Use the ``COMPARE`` keyword to select the comparison method for sorting.
|
||||
The ``<compare>`` option should be one of:
|
||||
|
||||
* ``STRING``: Sorts a list of strings alphabetically. This is the
|
||||
default behavior if the ``COMPARE`` option is not given.
|
||||
* ``FILE_BASENAME``: Sorts a list of pathnames of files by their basenames.
|
||||
* ``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.
|
||||
``STRING``
|
||||
Sorts a list of strings alphabetically.
|
||||
This is the default behavior if the ``COMPARE`` option is not given.
|
||||
|
||||
Use the ``CASE`` keyword to select a case sensitive or case insensitive
|
||||
sort mode. The ``<case>`` option should be one of:
|
||||
``FILE_BASENAME``
|
||||
Sorts a list of pathnames of files by their basenames.
|
||||
|
||||
* ``SENSITIVE``: List items are sorted in a case-sensitive manner. 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.
|
||||
``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.
|
||||
|
||||
To control the sort order, the ``ORDER`` keyword can be given.
|
||||
The ``<order>`` option should be one of:
|
||||
Use the ``CASE`` keyword to select a case sensitive or case insensitive
|
||||
sort mode. The ``<case>`` 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.
|
||||
``SENSITIVE``
|
||||
List items are sorted in a case-sensitive manner.
|
||||
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
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
.. signature::
|
||||
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
|
||||
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:`block` command. This command will set the value of a variable into
|
||||
the parent directory, calling function or encompassing scope (whichever is
|
||||
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
|
||||
still undefined and if it had a value, it is still that value).
|
||||
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`
|
||||
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
|
||||
the parent directory, calling function or encompassing scope (whichever is
|
||||
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
|
||||
still undefined and if it had a value, it is still that value).
|
||||
|
||||
The :command:`block(PROPAGATE)` and :command:`return(PROPAGATE)` commands can
|
||||
be used as an alternate method to the :command:`set(PARENT_SCOPE)` and
|
||||
:command:`unset(PARENT_SCOPE)` commands to update the parent scope.
|
||||
The :command:`block(PROPAGATE)` and :command:`return(PROPAGATE)` commands
|
||||
can be used as an alternate method to the :command:`set(PARENT_SCOPE)`
|
||||
and :command:`unset(PARENT_SCOPE)` commands to update the parent scope.
|
||||
|
||||
Set Cache Entry
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
.. signature::
|
||||
set(<variable> <value>... CACHE <type> <docstring> [FORCE])
|
||||
:target: CACHE
|
||||
|
||||
Sets the given cache ``<variable>`` (cache entry). Since cache entries
|
||||
are meant to provide user-settable values this does not overwrite
|
||||
existing cache entries by default. Use the ``FORCE`` option to
|
||||
overwrite existing entries.
|
||||
Sets the given cache ``<variable>`` (cache entry). Since cache entries
|
||||
are meant to provide user-settable values this does not overwrite
|
||||
existing cache entries by default. Use the ``FORCE`` option to
|
||||
overwrite existing entries.
|
||||
|
||||
The ``<type>`` must be specified as one of:
|
||||
The ``<type>`` must be specified as one of:
|
||||
|
||||
``BOOL``
|
||||
Boolean ``ON/OFF`` value. :manual:`cmake-gui(1)` offers a checkbox.
|
||||
``BOOL``
|
||||
Boolean ``ON/OFF`` value.
|
||||
:manual:`cmake-gui(1)` offers a checkbox.
|
||||
|
||||
``FILEPATH``
|
||||
Path to a file on disk. :manual:`cmake-gui(1)` offers a file dialog.
|
||||
``FILEPATH``
|
||||
Path to a file on disk.
|
||||
:manual:`cmake-gui(1)` offers a file dialog.
|
||||
|
||||
``PATH``
|
||||
Path to a directory on disk. :manual:`cmake-gui(1)` offers a file dialog.
|
||||
``PATH``
|
||||
Path to a directory on disk.
|
||||
:manual:`cmake-gui(1)` offers a file dialog.
|
||||
|
||||
``STRING``
|
||||
A line of text. :manual:`cmake-gui(1)` offers a text field or a
|
||||
drop-down selection if the :prop_cache:`STRINGS` cache entry
|
||||
property is set.
|
||||
``STRING``
|
||||
A line of text.
|
||||
:manual:`cmake-gui(1)` offers a text field or a drop-down selection
|
||||
if the :prop_cache:`STRINGS` cache entry property is set.
|
||||
|
||||
``INTERNAL``
|
||||
A line of text. :manual:`cmake-gui(1)` does not show internal entries.
|
||||
They may be used to store variables persistently across runs.
|
||||
Use of this type implies ``FORCE``.
|
||||
``INTERNAL``
|
||||
A line of text.
|
||||
:manual:`cmake-gui(1)` does not show internal entries.
|
||||
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
|
||||
a quick summary of the option for presentation to :manual:`cmake-gui(1)`
|
||||
users.
|
||||
The ``<docstring>`` must be specified as a line of text
|
||||
providing a quick summary of the option
|
||||
for presentation to :manual:`cmake-gui(1)` users.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
.. note::
|
||||
.. note::
|
||||
|
||||
The content of the cache variable will not be directly accessible if a normal
|
||||
variable of the same name already exists (see :ref:`rules of variable
|
||||
evaluation <CMake Language Variables>`). If policy :policy:`CMP0126` is set
|
||||
to ``OLD``, any normal variable binding in the current scope will be removed.
|
||||
The content of the cache variable will not be directly accessible
|
||||
if a normal variable of the same name already exists
|
||||
(see :ref:`rules of variable evaluation <CMake Language Variables>`).
|
||||
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
|
||||
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
|
||||
specifying a type. In this case the ``set`` command will add the
|
||||
type. Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH``
|
||||
and the ``<value>`` provided on the command line is a relative path,
|
||||
then the ``set`` command will treat the path as relative to the
|
||||
current working directory and convert it to an absolute path.
|
||||
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
|
||||
line by a user through the :option:`-D\<var\>=\<value\> <cmake -D>` option
|
||||
without specifying a type. In this case the ``set`` command will add the
|
||||
type. Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH``
|
||||
and the ``<value>`` provided on the command line is a relative path,
|
||||
then the ``set`` command will treat the path as relative to the
|
||||
current working directory and convert it to an absolute path.
|
||||
|
||||
Set Environment Variable
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
.. signature::
|
||||
set(ENV{<variable>} [<value>])
|
||||
:target: ENV
|
||||
|
||||
Sets an :manual:`Environment Variable <cmake-env-variables(7)>`
|
||||
to the given value.
|
||||
Subsequent calls of ``$ENV{<variable>}`` will return this new value.
|
||||
Sets an :manual:`Environment Variable <cmake-env-variables(7)>`
|
||||
to the given value.
|
||||
Subsequent calls of ``$ENV{<variable>}`` will return this new value.
|
||||
|
||||
This command affects only the current CMake process, not the process
|
||||
from which CMake was called, nor the system environment at large,
|
||||
nor the environment of subsequent build or test processes.
|
||||
This command affects only the current CMake process, not the process
|
||||
from which CMake was called, nor the system environment at large,
|
||||
nor the environment of subsequent build or test processes.
|
||||
|
||||
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
|
||||
environment variable.
|
||||
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
|
||||
environment variable.
|
||||
|
||||
Arguments after ``<value>`` are ignored. If extra arguments are found,
|
||||
then an author warning is issued.
|
||||
Arguments after ``<value>`` are ignored. If extra arguments are found,
|
||||
then an author warning is issued.
|
||||
|
||||
See Also
|
||||
^^^^^^^^
|
||||
|
||||
Reference in New Issue
Block a user