list

Операции над списками, разделёнными точкой с запятой.

Сводка

Reading
  list(LENGTH <list> <out-var>)
  list(GET <list> <element index> [<index> ...] <out-var>)
  list(JOIN <list> <glue> <out-var>)
  list(SUBLIST <list> <begin> <length> <out-var>)

Search
  list(FIND <list> <value> <out-var>)

Modification
  list(APPEND <list> [<element>...])
  list(FILTER <list> <INCLUDE|EXCLUDE> <MODE>)
  list(INSERT <list> <index> [<element>...])
  list(POP_BACK <list> [<out-var>...])
  list(POP_FRONT <list> [<out-var>...])
  list(PREPEND <list> [<element>...])
  list(REMOVE_ITEM <list> <value>...)
  list(REMOVE_AT <list> <index>...)
  list(REMOVE_DUPLICATES <list>)
  list(TRANSFORM <list> <ACTION> [...])

Ordering
  list(REVERSE <list>)
  list(SORT <list> [...])

Введение

Подкоманды list APPEND, INSERT, FILTER, PREPEND, POP_BACK, POP_FRONT, REMOVE_AT, REMOVE_ITEM, REMOVE_DUPLICATES, REVERSE и SORT могут создавать новые значения списка в текущей области видимости переменных CMake. Подобно команде set(), команда list создаёт новые значения переменных в текущей области видимости, даже если сам список фактически определён в родительской области видимости. Чтобы передать результаты этих операций в вышестоящие области видимости, используйте set() с PARENT_SCOPE, set() с CACHE INTERNAL или другой способ передачи значений.

Примечание

Список в CMake — это группа строк, разделённых символом ;. Для создания списка можно использовать команду set(). Например, set(var a b c d e) создаёт список со значением a;b;c;d;e, а set(var "a b c d e") создаёт строку или список с одним элементом. (Обратите внимание, что аргументы макросов не являются переменными, поэтому их нельзя использовать в командах LIST.)

Отдельные элементы не могут содержать разное количество символов [ и ] и не могут оканчиваться обратной косой чертой (\). Подробности см. в разделе списки, разделённые точкой с запятой.

Примечание

При указании индексов, если <element index> равно 0 или больше, отсчёт ведётся от начала списка, где 0 обозначает первый элемент. Если <element index> равно -1 или меньше, отсчёт ведётся от конца списка, где -1 обозначает последний элемент. Будьте осторожны при подсчёте с отрицательными индексами: отсчёт для них начинается не с 0. Значение -0 эквивалентно 0 — индексу первого элемента списка.

Чтение

list(LENGTH <list> <output variable>): Возвращает длину списка.

list(GET <list> <element index> [<element index> ...] <output variable>): Возвращает элементы списка, указанные индексами.

list(JOIN <list> <glue> <output variable>): Добавлено в версии 3.12.

Возвращает строку, объединяющую все элементы списка с помощью строки-разделителя. Чтобы объединить несколько строк, не входящих в список, используйте string(JOIN).

list(SUBLIST <list> <begin> <length> <output variable>): Добавлено в версии 3.12.

Возвращает подсписок заданного списка. Если <length> равно 0, будет возвращён пустой список. Если <length> равно -1 или список короче, чем <begin>+<length>, будут возвращены оставшиеся элементы списка, начиная с <begin>.

Поиск

list(FIND <list> <value> <output variable>): Возвращает индекс указанного элемента в списке или -1, если элемент не найден.

Изменение

list(APPEND <list> [<element> ...]): Добавляет элементы в конец списка. Если в текущей области видимости нет переменной с именем <list>, её значение считается пустым, и элементы добавляются в этот пустой список.

list(FILTER <list> <INCLUDE|EXCLUDE> <MODE>)

Добавлено в версии 3.6.

Добавляет в список или удаляет из него элементы, соответствующие шаблону режима.

<MODE> должно быть одним из следующих значений:

REGEX

Элементы сопоставляются с заданным регулярным выражением.

list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)

Дополнительные сведения о регулярных выражениях см. в разделе string(REGEX).

PREDICATE

Укажите пользовательскую function() в качестве предиката.

list(FILTER <list> <INCLUDE|EXCLUDE> PREDICATE <function>)

Добавлено в версии 4.4.

<function> — это пользовательская function(), выполняющая роль унарного предиката. Функция должна принимать ровно два параметра: входное значение и имя выходной переменной. Функция должна установить выходную переменную в логическое значение в вызывающей области видимости. Значение выходной переменной интерпретируется с помощью стандартных правил вычисления логических значений CMake. Если функция не установит выходную переменную, возникнет ошибка.

Пример:

function(file_exists path result)
  if(EXISTS "${path}")
    set(${result} TRUE PARENT_SCOPE)
  else()
    set(${result} FALSE PARENT_SCOPE)
  endif()
endfunction()

set(candidate_files main.c missing.c utils.c)
list(FILTER candidate_files INCLUDE PREDICATE file_exists)

list(INSERT <list> <element_index> <element> [<element> ...]): Вставляет элементы в список по указанному индексу. Указание индекса вне допустимого диапазона приводит к ошибке. Допустимы индексы от 0 до N включительно, где N — длина списка. Длина пустого списка равна 0. Если в текущей области видимости нет переменной с именем <list>, её значение считается пустым, и элементы вставляются в этот пустой список.

list(POP_BACK <list> [<out-var>...]): Добавлено в версии 3.15.

Если имя переменной не указано, удаляется ровно один элемент. В противном случае, если указано N имён переменных, значения последних N элементов присваиваются этим переменным, после чего последние N значений удаляются из <list>.

list(POP_FRONT <list> [<out-var>...]): Добавлено в версии 3.15.

Если имя переменной не указано, удаляется ровно один элемент. В противном случае, если указано N имён переменных, значения первых N элементов присваиваются этим переменным, после чего первые N значений удаляются из <list>.

list(PREPEND <list> [<element> ...]): Добавлено в версии 3.15.

Вставляет элементы в начало списка (на позицию 0). Если в текущей области видимости нет переменной с именем <list>, её значение считается пустым, и элементы добавляются в начало этого пустого списка.

list(REMOVE_ITEM <list> <value> [<value> ...]): Удаляет из списка все вхождения указанных элементов.

list(REMOVE_AT <list> <index> [<index> ...]): Удаляет из списка элементы с указанными индексами.

list(REMOVE_DUPLICATES <list>): Удаляет повторяющиеся элементы списка. Относительный порядок элементов сохраняется; если обнаружены дубликаты, остаётся только первое вхождение.

list(TRANSFORM <list> <ACTION> [<SELECTOR>] [OUTPUT_VARIABLE <output variable>])

Добавлено в версии 3.12.

Преобразует список, применяя <ACTION> ко всем его элементам или, при указании <SELECTOR>, к выбранным элементам, и сохраняет результат в исходном списке либо в указанной выходной переменной.

Примечание

Подкоманда TRANSFORM не изменяет количество элементов в списке. Если задан <SELECTOR>, изменяются только некоторые элементы, а остальные остаются такими же, как до преобразования.

<ACTION> задаёт действие, применяемое к элементам списка. <ACTION> должно быть одним из следующих значений:

APPEND, PREPEND

Добавляет указанное значение в конец или начало каждого элемента списка.

list(TRANSFORM <list> (APPEND|PREPEND) <value> ...)

TOLOWER, TOUPPER

Преобразует каждый элемент списка в нижний или верхний регистр.

list(TRANSFORM <list> (TOLOWER|TOUPPER) ...)

STRIP

Удаляет начальные и конечные пробелы из каждого элемента списка.

list(TRANSFORM <list> STRIP ...)

GENEX_STRIP

Удаляет все generator expressions из каждого элемента списка.

list(TRANSFORM <list> GENEX_STRIP ...)

REPLACE

Находит все возможные совпадения с регулярным выражением и заменяет каждое совпадение выражением замены в каждом элементе списка (семантика совпадает с string(REGEX REPLACE)).

list(TRANSFORM <list> REPLACE <regular_expression> <replace_expression> ...)

Изменено в версии 4.1: Якорь ^ теперь соответствует только началу входного элемента, а не началу каждого повторного поиска. См. политику CMP0186.

APPLY

Вызывает пользовательскую function() для каждого элемента списка. Функция должна принимать ровно два параметра: входное значение и имя выходной переменной. Функция должна установить выходную переменную в вызывающей области видимости.

list(TRANSFORM <list> APPLY <function> ...)

Добавлено в версии 4.4.

<function> — это function() ровно с двумя формальными параметрами. Установите выходную переменную с помощью set(<variable> <value> PARENT_SCOPE):

function(<function> <input> <output>)
  # Transform <input>, store result in ${<output>}
  set(${<output>} "<result>" PARENT_SCOPE)
endfunction()

Перед каждым вызовом выходная переменная сбрасывается в вызывающей области видимости, чтобы исключить использование устаревших значений.

Пример:

function(make_absolute in out)
  cmake_path(ABSOLUTE_PATH in BASE_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}")
  set(${out} "${in}" PARENT_SCOPE)
endfunction()

set(mylist main.c utils.c io.c)
list(TRANSFORM mylist APPLY make_absolute)
# mylist is now absolute paths relative to CMAKE_CURRENT_SOURCE_DIR

<SELECTOR> определяет, какие элементы списка будут преобразованы. За один раз можно указать только один тип селектора. При указании <SELECTOR> должно быть одним из следующих значений:

AT

Указывает список индексов.

list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)

FOR

Указывает диапазон с необязательным шагом для перебора его значений.

list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)

REGEX

Указывает регулярное выражение. Преобразуются только элементы, соответствующие регулярному выражению.

list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)

PREDICATE

Указывает пользовательскую function() в качестве предиката. Преобразуются только элементы, для которых функция возвращает истинное значение.

list(TRANSFORM <list> <ACTION> PREDICATE <function> ...)

Добавлено в версии 4.4.

<function> — это пользовательская function() ровно с двумя формальными параметрами: входным значением и именем выходной переменной. Функция должна установить выходную переменную в логическое значение. Используются стандартные правила вычисления логических значений CMake. Если функция не установит выходную переменную, возникнет ошибка.

Пример:

function(is_relative path result)
  if(NOT IS_ABSOLUTE "${path}")
    set(${result} TRUE PARENT_SCOPE)
  else()
    set(${result} FALSE PARENT_SCOPE)
  endif()
endfunction()

set(search_paths /usr/include src lib /opt/lib)
list(TRANSFORM search_paths PREPEND "${CMAKE_CURRENT_SOURCE_DIR}/"
     PREDICATE is_relative)

Упорядочивание

list(REVERSE <list>): Обращает порядок элементов списка на месте.

list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])

list(SORT<list>COMPARATOR<function>[CASE<case>][ORDER<order>])

Сортирует список по алфавиту на месте.

Добавлено в версии 3.13: Добавлены параметры COMPARE, CASE и ORDER.

Добавлено в версии 3.18: Добавлен параметр COMPARE NATURAL.

Используйте ключевое слово COMPARE, чтобы выбрать метод сравнения для сортировки. Параметр <compare> должен иметь одно из следующих значений:

STRING: Сортирует список строк по алфавиту. Это поведение по умолчанию, если параметр COMPARE не указан.
FILE_BASENAME: Сортирует список путей к файлам по их базовым именам.
NATURAL: Сортирует список строк в естественном порядке (см. руководство strverscmp(3)), то есть последовательности цифр сравниваются как целые числа. Например, следующий список 10.0 1.1 2.1 8.0 2.0 3.1 будет отсортирован как 1.1 2.0 2.1 3.1 8.0 10.0, если выбран режим сравнения NATURAL; при режиме сравнения STRING он будет отсортирован как 1.1 10.0 2.0 2.1 3.1 8.0.

Используйте ключевое слово CASE, чтобы выбрать сортировку с учётом или без учёта регистра. Параметр <case> должен иметь одно из следующих значений:

SENSITIVE: Элементы списка сортируются с учётом регистра. Это поведение по умолчанию, если параметр CASE не указан.
INSENSITIVE: Элементы списка сортируются без учёта регистра. Порядок элементов, различающихся только регистром, не определён.

Для управления порядком сортировки можно указать ключевое слово ORDER. Параметр <order> должен иметь одно из следующих значений:

ASCENDING: Сортирует список по возрастанию. Это поведение по умолчанию, если параметр ORDER не указан.
DESCENDING: Сортирует список по убыванию.

Вместо встроенных методов COMPARE с ключевым словом COMPARATOR можно использовать пользовательскую функцию сравнения function().

Добавлено в версии 4.4.

COMPARATOR нельзя использовать одновременно с COMPARE. Параметры CASE и ORDER по-прежнему можно использовать вместе с COMPARATOR: фильтр CASE применяется к обоим значениям перед передачей функции, а ORDER DESCENDING меняет порядок сравнения, переставляя аргументы местами.

Функция должна принимать ровно три параметра: два входных значения и имя выходной переменной. Она должна установить выходную переменную в логическое значение (TRUE, если первое значение должно идти перед вторым, и FALSE в противном случае) в вызывающей области видимости. Если функция не установит выходную переменную, возникнет ошибка.

Функция сравнения должна задавать строгий слабый порядок. В частности:

При сравнении элемента с самим собой она должна возвращать FALSE (антирефлексивность).
Если для (a, b) она возвращает TRUE, то для (b, a) она должна возвращать FALSE (асимметричность).

Если функция сравнения нарушает эти требования, возникает ошибка.

Пример:

function(version_less a b result)
  if("${a}" VERSION_LESS "${b}")
    set(${result} TRUE PARENT_SCOPE)
  else()
    set(${result} FALSE PARENT_SCOPE)
  endif()
endfunction()

set(versions 3.1 1.2 2.0 1.10)
list(SORT versions COMPARATOR version_less)
# versions is now: 1.2;1.10;2.0;3.1

© 2000–2026 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/latest/command/list.html