diff options
-rw-r--r-- | Help/command/list.rst | 364 | ||||
-rw-r--r-- | Help/command/set.rst | 161 |
2 files changed, 248 insertions, 277 deletions
diff --git a/Help/command/list.rst b/Help/command/list.rst index 33c4f80d24..191003a700 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -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. - -.. _JOIN: + Returns the list of elements specified by indices from the list. -.. code-block:: cmake +.. signature:: list(JOIN <list> <glue> <output variable>) - list(JOIN <list> <glue> <output variable>) + .. versionadded:: 3.12 -.. 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 - -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>``. + .. versionadded:: 3.15 -.. _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 - -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. + .. versionadded:: 3.15 -.. _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: +.. signature:: + list(REVERSE <list>) -.. code-block:: cmake + Reverses the contents of the list in-place. - list(REVERSE <list>) +.. signature:: + list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>]) -Reverses the contents of the list in-place. + Sorts the list in-place alphabetically. -.. _SORT: + .. versionadded:: 3.13 + Added the ``COMPARE``, ``CASE``, and ``ORDER`` options. -.. code-block:: cmake + .. versionadded:: 3.18 + Added the ``COMPARE NATURAL`` option. - list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>]) + Use the ``COMPARE`` keyword to select the comparison method for sorting. + The ``<compare>`` option should be one of: -Sorts the list in-place alphabetically. + ``STRING`` + Sorts a list of strings alphabetically. + This is the default behavior if the ``COMPARE`` option is not given. -.. versionadded:: 3.13 - Added the ``COMPARE``, ``CASE``, and ``ORDER`` options. + ``FILE_BASENAME`` + Sorts a list of pathnames of files by their basenames. -.. versionadded:: 3.18 - Added the ``COMPARE NATURAL`` option. + ``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 ``COMPARE`` keyword to select the comparison method for sorting. -The ``<compare>`` 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: -* ``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. + ``SENSITIVE`` + List items are sorted in a case-sensitive manner. + This is the default behavior if the ``CASE`` 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: + ``INSENSITIVE`` + List items are sorted case insensitively. The order of + items which differ only by upper/lowercase is not specified. -* ``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: -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. -* ``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. + ``DESCENDING`` + Sorts the list in descending order. diff --git a/Help/command/set.rst b/Help/command/set.rst index c724844813..ee677c991e 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -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]) - -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: - -``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. - -``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. - -``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. - -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:: - - 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. + :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. + + The ``<type>`` must be specified as one of: + + ``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. + + ``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. + + ``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. + + 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:: + + 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. 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 ^^^^^^^^ |