|
|
|
@ -333,6 +333,15 @@ Most of the expressions in this section are closely associated with the
|
|
|
|
|
:command:`list` command, providing the same capabilities, but in
|
|
|
|
|
the form of a generator expression.
|
|
|
|
|
|
|
|
|
|
In each of the following list-related generator expressions, the ``list``
|
|
|
|
|
must not contain any commas if that generator expression expects something to
|
|
|
|
|
be provided after the ``list``. For example, the expression
|
|
|
|
|
``$<LIST:FIND,list,value>`` requires a ``value`` after the ``list``.
|
|
|
|
|
Since a comma is used to separate the ``list`` and the ``value``, the ``list``
|
|
|
|
|
cannot itself contain a comma. This restriction does not apply to the
|
|
|
|
|
:command:`list` command, it is specific to the list-handling generator
|
|
|
|
|
expressions only.
|
|
|
|
|
|
|
|
|
|
.. _GenEx List Comparisons:
|
|
|
|
|
|
|
|
|
|
List Comparisons
|
|
|
|
@ -354,133 +363,151 @@ List Queries
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Returns the list's length.
|
|
|
|
|
The number of items in the ``list``.
|
|
|
|
|
|
|
|
|
|
.. genex:: $<LIST:GET,list,index,...>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Returns the list of elements specified by indices from the list.
|
|
|
|
|
Expands to the list of items specified by indices from the ``list``.
|
|
|
|
|
|
|
|
|
|
.. genex:: $<LIST:SUBLIST,list,begin,length>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
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``, the remaining items of the list starting at
|
|
|
|
|
``begin`` will be returned.
|
|
|
|
|
|
|
|
|
|
.. genex:: $<LIST:FIND,list,value>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Returns the index of the element specified in the list or -1 if it wasn't
|
|
|
|
|
found.
|
|
|
|
|
The index of the first item in ``list`` with the specified ``value``,
|
|
|
|
|
or -1 if ``value`` is not in the ``list``.
|
|
|
|
|
|
|
|
|
|
.. _GenEx List Transformations:
|
|
|
|
|
|
|
|
|
|
List Transformations
|
|
|
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
.. _GenEx LIST-JOIN:
|
|
|
|
|
|
|
|
|
|
.. genex:: $<LIST:JOIN,list,glue>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Returns a string which joins the list with the content of the ``glue`` string
|
|
|
|
|
inserted between each item.
|
|
|
|
|
Converts ``list`` to a single string with the content of the ``glue`` string
|
|
|
|
|
inserted between each item. This is conceptually the same operation as
|
|
|
|
|
:genex:`$<JOIN:list,glue>`, but the two have different behavior with regard
|
|
|
|
|
to empty items. ``$<LIST:JOIN,list,glue>`` preserves all empty items,
|
|
|
|
|
whereas :genex:`$<JOIN:list,glue>` drops all empty items from the list.
|
|
|
|
|
|
|
|
|
|
.. genex:: $<LIST:APPEND,list,element,...>
|
|
|
|
|
.. genex:: $<LIST:APPEND,list,item,...>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Returns a list with the elements appended.
|
|
|
|
|
The ``list`` with each ``item`` appended. Multiple items should be
|
|
|
|
|
separated by commas.
|
|
|
|
|
|
|
|
|
|
.. genex:: $<LIST:PREPEND,list,element,...>
|
|
|
|
|
.. genex:: $<LIST:PREPEND,list,item,...>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Returns a list with the elements inserted at the beginning of the list.
|
|
|
|
|
The ``list`` with each ``item`` inserted at the beginning. If there are
|
|
|
|
|
multiple items, they should be separated by commas, and the order of the
|
|
|
|
|
prepended items will be preserved.
|
|
|
|
|
|
|
|
|
|
.. genex:: $<LIST:INSERT,list,index,element,...>
|
|
|
|
|
.. genex:: $<LIST:INSERT,list,index,item,...>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Returns a list with the elements inserted at 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.
|
|
|
|
|
The ``list`` with the ``item`` (or multiple items) inserted at the specified
|
|
|
|
|
``index``. Multiple items should be separated by commas.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
.. genex:: $<LIST:POP_BACK,list>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Returns a list with the last element was removed.
|
|
|
|
|
The ``list`` with the last item removed.
|
|
|
|
|
|
|
|
|
|
.. genex:: $<LIST:POP_FRONT,list>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Returns a list with the first element was removed.
|
|
|
|
|
The ``list`` with the first item removed.
|
|
|
|
|
|
|
|
|
|
.. genex:: $<LIST:REMOVE_ITEM,list,value,...>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Returns a list with all instances of the given values were removed.
|
|
|
|
|
The ``list`` with all instances of the given ``value`` (or values) removed.
|
|
|
|
|
If multiple values are given, they should be separated by commas.
|
|
|
|
|
|
|
|
|
|
.. genex:: $<LIST:REMOVE_AT,list,index,...>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Returns a list with all values at given indices were removed.
|
|
|
|
|
The ``list`` with the item at each given ``index`` removed.
|
|
|
|
|
|
|
|
|
|
.. _GenEx LIST-REMOVE_DUPLICATES:
|
|
|
|
|
|
|
|
|
|
.. genex:: $<LIST:REMOVE_DUPLICATES,list>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Returns a list where duplicated items were removed. The relative order of
|
|
|
|
|
The ``list`` with all duplicated items removed. The relative order of
|
|
|
|
|
items is preserved, but if duplicates are encountered, only the first
|
|
|
|
|
instance is preserved.
|
|
|
|
|
instance is preserved. The result is the same as
|
|
|
|
|
:genex:`$<REMOVE_DUPLICATES:list>`.
|
|
|
|
|
|
|
|
|
|
.. _GenEx LIST-FILTER:
|
|
|
|
|
|
|
|
|
|
.. genex:: $<LIST:FILTER,list,INCLUDE|EXCLUDE,regex>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Returns a list with the items that match the regular expression ``regex``
|
|
|
|
|
were included or removed.
|
|
|
|
|
A list of items from the ``list`` which match (``INCLUDE``) or do not match
|
|
|
|
|
(``EXCLUDE``) the regular expression ``regex``. The result is the same as
|
|
|
|
|
:genex:`$<FILTER:list,INCLUDE|EXCLUDE,regex>`.
|
|
|
|
|
|
|
|
|
|
.. genex:: $<LIST:TRANSFORM,list,ACTION[,SELECTOR]>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Returns the list transformed by applying an ``ACTION`` to all or, by
|
|
|
|
|
specifying a ``SELECTOR``, to the selected elements of the list.
|
|
|
|
|
The ``list`` transformed by applying an ``ACTION`` to all or, by
|
|
|
|
|
specifying a ``SELECTOR``, to the selected list items.
|
|
|
|
|
|
|
|
|
|
.. 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 ``TRANSFORM`` sub-command does not change the number of items in the
|
|
|
|
|
list. If a ``SELECTOR`` is specified, only some items 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 of the
|
|
|
|
|
``ACTION`` specifies the action to apply to the items of the list.
|
|
|
|
|
The actions have exactly the same semantics as for the
|
|
|
|
|
:command:`list(TRANSFORM)` command. ``ACTION`` must be one of the following:
|
|
|
|
|
|
|
|
|
|
:command:`APPEND <list(TRANSFORM_APPEND)>`, :command:`PREPEND <list(TRANSFORM_APPEND)>`
|
|
|
|
|
Append, prepend specified value to each element of the list.
|
|
|
|
|
Append, prepend specified value to each item of the list.
|
|
|
|
|
|
|
|
|
|
.. code-block:: cmake
|
|
|
|
|
|
|
|
|
|
$<LIST:TRANSFORM,list,(APPEND|PREPEND),value[,SELECTOR]>
|
|
|
|
|
|
|
|
|
|
:command:`TOLOWER <list(TRANSFORM_TOLOWER)>`, :command:`TOUPPER <list(TRANSFORM_TOLOWER)>`
|
|
|
|
|
Convert each element of the list to lower, upper characters.
|
|
|
|
|
Convert each item of the list to lower, upper characters.
|
|
|
|
|
|
|
|
|
|
.. code-block:: cmake
|
|
|
|
|
|
|
|
|
|
$<LIST:TRANSFORM,list,(TOLOWER|TOUPPER)[,SELECTOR]>
|
|
|
|
|
|
|
|
|
|
:command:`STRIP <list(TRANSFORM_STRIP)>`
|
|
|
|
|
Remove leading and trailing spaces from each element of the list.
|
|
|
|
|
Remove leading and trailing spaces from each item of the list.
|
|
|
|
|
|
|
|
|
|
.. code-block:: cmake
|
|
|
|
|
|
|
|
|
@ -488,13 +515,13 @@ List Transformations
|
|
|
|
|
|
|
|
|
|
:command:`REPLACE <list(TRANSFORM_REPLACE)>`:
|
|
|
|
|
Match the regular expression as many times as possible and substitute
|
|
|
|
|
the replacement expression for the match for each element of the list.
|
|
|
|
|
the replacement expression for the match for each item of the list.
|
|
|
|
|
|
|
|
|
|
.. code-block:: cmake
|
|
|
|
|
|
|
|
|
|
$<LIST:TRANSFORM,list,REPLACE,regular_expression,replace_expression[,SELECTOR]>
|
|
|
|
|
|
|
|
|
|
``SELECTOR`` determines which elements of the list will be transformed.
|
|
|
|
|
``SELECTOR`` determines which items 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:
|
|
|
|
|
|
|
|
|
@ -515,7 +542,7 @@ List Transformations
|
|
|
|
|
|
|
|
|
|
``REGEX``
|
|
|
|
|
Specify a regular expression.
|
|
|
|
|
Only elements matching the regular expression will be transformed.
|
|
|
|
|
Only items matching the regular expression will be transformed.
|
|
|
|
|
|
|
|
|
|
.. code-block:: cmake
|
|
|
|
|
|
|
|
|
@ -523,23 +550,29 @@ List Transformations
|
|
|
|
|
|
|
|
|
|
.. genex:: $<JOIN:list,glue>
|
|
|
|
|
|
|
|
|
|
Joins the list with the content of the ``glue`` string inserted between each
|
|
|
|
|
item.
|
|
|
|
|
Joins the ``list`` with the content of the ``glue`` string inserted between
|
|
|
|
|
each item. This is conceptually the same operation as
|
|
|
|
|
:ref:`$\<LIST:JOIN,list,glue\> <GenEx LIST-JOIN>`, but the two have
|
|
|
|
|
different behavior with regard to empty items.
|
|
|
|
|
:ref:`$\<LIST:JOIN,list,glue\> <GenEx LIST-JOIN>` preserves all empty items,
|
|
|
|
|
whereas ``$<JOIN,list,glue>`` drops all empty items from the list.
|
|
|
|
|
|
|
|
|
|
.. genex:: $<REMOVE_DUPLICATES:list>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.15
|
|
|
|
|
|
|
|
|
|
Removes duplicated items in the given ``list``. The relative order of items
|
|
|
|
|
is preserved, but if duplicates are encountered, only the first instance is
|
|
|
|
|
preserved.
|
|
|
|
|
is preserved, and if duplicates are encountered, only the first instance is
|
|
|
|
|
retained. The result is the same as
|
|
|
|
|
:ref:`$\<LIST:REMOVE_DUPLICATES,list\> <GenEx LIST-REMOVE_DUPLICATES>`.
|
|
|
|
|
|
|
|
|
|
.. genex:: $<FILTER:list,INCLUDE|EXCLUDE,regex>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.15
|
|
|
|
|
|
|
|
|
|
Includes or removes items from ``list`` that match the regular expression
|
|
|
|
|
``regex``.
|
|
|
|
|
``regex``. The result is the same as
|
|
|
|
|
:ref:`$\<LIST:FILTER,list,INCLUDE|EXCLUDE,regex\> <GenEx LIST-FILTER>`.
|
|
|
|
|
|
|
|
|
|
.. _GenEx List Ordering:
|
|
|
|
|
|
|
|
|
@ -550,13 +583,13 @@ List Ordering
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Returns the list with the elements in reverse order.
|
|
|
|
|
The ``list`` with the items in reverse order.
|
|
|
|
|
|
|
|
|
|
.. genex:: $<LIST:SORT,list[,(COMPARE:option|CASE:option|ORDER:option)]...>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Returns the list sorted according the specified options.
|
|
|
|
|
The ``list`` sorted according to the specified options.
|
|
|
|
|
|
|
|
|
|
Use one of the ``COMPARE`` options to select the comparison method
|
|
|
|
|
for sorting:
|
|
|
|
@ -566,26 +599,25 @@ List Ordering
|
|
|
|
|
This is the default behavior if the ``COMPARE`` option is not given.
|
|
|
|
|
|
|
|
|
|
``FILE_BASENAME``
|
|
|
|
|
Sorts a list of pathnames of files by their basenames.
|
|
|
|
|
Sorts a list of file paths 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.
|
|
|
|
|
Sorts a list of strings using natural order (see the man page for
|
|
|
|
|
``strverscmp(3)``), 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, whereas it will be sorted as
|
|
|
|
|
``1.1 10.0 2.0 2.1 3.1 8.0`` with the ``STRING`` comparison.
|
|
|
|
|
|
|
|
|
|
Use one of the ``CASE`` options to select a case sensitive or case
|
|
|
|
|
insensitive sort mode:
|
|
|
|
|
Use one of the ``CASE`` options to select a case-sensitive or
|
|
|
|
|
case-insensitive sort mode:
|
|
|
|
|
|
|
|
|
|
``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
|
|
|
|
|
List items are sorted in a case-insensitive manner. The order of
|
|
|
|
|
items which differ only by upper/lowercase is not specified.
|
|
|
|
|
|
|
|
|
|
To control the sort order, one of the ``ORDER`` options can be given:
|
|
|
|
@ -597,8 +629,8 @@ List Ordering
|
|
|
|
|
``DESCENDING``
|
|
|
|
|
Sorts the list in descending order.
|
|
|
|
|
|
|
|
|
|
This is an error to specify multiple times the same option. Various options
|
|
|
|
|
can be specified in any order:
|
|
|
|
|
Options can be specified in any order, but it is an error to specify the
|
|
|
|
|
same option multiple times.
|
|
|
|
|
|
|
|
|
|
.. code-block:: cmake
|
|
|
|
|
|
|
|
|
@ -1789,20 +1821,20 @@ In the following, the phrase "the ``tgt`` filename" means the name of the
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Full path to the linker import file. On DLL platforms, it would be the
|
|
|
|
|
``.lib`` file. On AIX, for the executables, and on macOS, for the shared
|
|
|
|
|
libraries, it could be, respectively, the ``.imp`` or ``.tbd`` import file,
|
|
|
|
|
depending of the value of :prop_tgt:`ENABLE_EXPORTS` property.
|
|
|
|
|
``.lib`` file. For executables on AIX, and for shared libraries on macOS,
|
|
|
|
|
it could be, respectively, the ``.imp`` or ``.tbd`` import file,
|
|
|
|
|
depending on the value of the :prop_tgt:`ENABLE_EXPORTS` property.
|
|
|
|
|
|
|
|
|
|
An empty string is returned when there is no import file associated with the
|
|
|
|
|
target.
|
|
|
|
|
This expands to an empty string when there is no import file associated
|
|
|
|
|
with the target.
|
|
|
|
|
|
|
|
|
|
.. genex:: $<TARGET_IMPORT_FILE_BASE_NAME:tgt>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Base name of file linker import file of the target ``tgt`` without prefix and
|
|
|
|
|
suffix. For example, if target file name is ``libbase.tbd``, the base name is
|
|
|
|
|
``base``.
|
|
|
|
|
Base name of the linker import file of the target ``tgt`` without prefix or
|
|
|
|
|
suffix. For example, if the target file name is ``libbase.tbd``, the base
|
|
|
|
|
name is ``base``.
|
|
|
|
|
|
|
|
|
|
See also the :prop_tgt:`OUTPUT_NAME` and :prop_tgt:`ARCHIVE_OUTPUT_NAME`
|
|
|
|
|
target properties and their configuration specific variants
|
|
|
|
@ -1831,7 +1863,7 @@ In the following, the phrase "the ``tgt`` filename" means the name of the
|
|
|
|
|
|
|
|
|
|
Suffix of the import file of the target ``tgt``.
|
|
|
|
|
|
|
|
|
|
The suffix corresponds to the file extension (such as ".lib" or ".tbd").
|
|
|
|
|
The suffix corresponds to the file extension (such as ``.lib`` or ``.tbd``).
|
|
|
|
|
|
|
|
|
|
See also the :prop_tgt:`IMPORT_SUFFIX` target property.
|
|
|
|
|
|
|
|
|
@ -1842,13 +1874,15 @@ In the following, the phrase "the ``tgt`` filename" means the name of the
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Name of the import file of the target target ``tgt``.
|
|
|
|
|
Name of the import file of the target ``tgt``.
|
|
|
|
|
|
|
|
|
|
Note that ``tgt`` is not added as a dependency of the target this
|
|
|
|
|
expression is evaluated on.
|
|
|
|
|
|
|
|
|
|
.. genex:: $<TARGET_IMPORT_FILE_DIR:tgt>
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
|
|
|
|
|
Directory of the import file of the target ``tgt``.
|
|
|
|
|
|
|
|
|
|
Note that ``tgt`` is not added as a dependency of the target this
|
|
|
|
@ -1863,11 +1897,11 @@ In the following, the phrase "the ``tgt`` filename" means the name of the
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 3.27
|
|
|
|
|
On macOS, it could be the ``.tbd`` import file associated with the shared
|
|
|
|
|
library, depending of the value of :prop_tgt:`ENABLE_EXPORTS` property.
|
|
|
|
|
library, depending on the value of the :prop_tgt:`ENABLE_EXPORTS` property.
|
|
|
|
|
|
|
|
|
|
This generator expression is equivalent to
|
|
|
|
|
:genex:`$<TARGET_LINKER_LIBRARY_FILE>` or
|
|
|
|
|
:genex:`$<TARGET_LINKER_IMPORT_FILE>` generator expressions, depending of the
|
|
|
|
|
:genex:`$<TARGET_LINKER_IMPORT_FILE>` generator expressions, depending on the
|
|
|
|
|
characteristics of the target and the platform.
|
|
|
|
|
|
|
|
|
|
.. genex:: $<TARGET_LINKER_FILE_BASE_NAME:tgt>
|
|
|
|
|