cmake_parse_arguments

Обработка аргументов функции или макроса.

cmake_parse_arguments(<prefix> <options> <one_value_keywords>
                      <multi_value_keywords> <args>...)

cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options>
                      <one_value_keywords> <multi_value_keywords>)

Эта команда используется в макросах или функциях. Она обрабатывает аргументы, переданные этому макросу или функции, и определяет набор переменных, содержащих значения соответствующих опций.

Первый синтаксис считывает аргументы, переданные в <args>.... Это можно использовать как в macro(), так и в function().

Аргумент <options> содержит все опции для соответствующей функции или макроса. Это ключевые слова без последующих значений, например, ключевое слово OPTIONAL команды install().

Аргумент <one_value_keywords> содержит все ключевые слова для этой функции или макроса, за которыми следует одно значение, например, ключевое слово DESTINATION команды install().

Аргумент <multi_value_keywords> содержит все ключевые слова для этой функции или макроса, за которыми может следовать более одного значения, например, ключевые слова TARGETS или FILES команды install().

По завершении, cmake_parse_arguments создаст для каждого ключевого слова, перечисленного в <options>, <one_value_keywords>, и <multi_value_keywords>, переменную, состоящую из заданного <prefix> плюс "_" и имени соответствующего ключевого слова. Для <one_value_keywords> и <multi_value_keywords> эти переменные будут содержать соответствующие значения(я) из списка аргументов или будут не определены, если соответствующее ключевое слово не было указано (политика CMP0174 также может повлиять на поведение для <one_value_keywords>). Для ключевых слов <options> эти переменные всегда будут определены и установлены в TRUE, если ключевое слово присутствует, или в FALSE, если его нет.

Все оставшиеся аргументы собираются в переменной <prefix>_UNPARSED_ARGUMENTS, которая будет не определена, если все аргументы были распознаны. Это можно проверить позже, чтобы увидеть, был ли ваш макрос или функция вызван с нераспознанными параметрами.

Тщательно выбирайте <prefix>, чтобы избежать конфликтов с имеющимися именами переменных. При использовании внутри функции обычно подходит префикс arg. Существует очень строгая конвенция, что все ключевые слова полностью прописные, поэтому этот префикс приводит к переменным типа arg_SOME_KEYWORD. Это делает код более читаемым и минимизирует вероятность конфликта с переменными кэша, которые также имеют строгую конвенцию — все прописные буквы.

function(my_install)
    set(options OPTIONAL FAST)
    set(oneValueArgs DESTINATION RENAME)
    set(multiValueArgs TARGETS CONFIGURATIONS)
    cmake_parse_arguments(PARSE_ARGV 0 arg
        "${options}" "${oneValueArgs}" "${multiValueArgs}"
    )

    # The above will set or unset variables with the following names:
    #   arg_OPTIONAL
    #   arg_FAST
    #   arg_DESTINATION
    #   arg_RENAME
    #   arg_TARGETS
    #   arg_CONFIGURATIONS
    #
    # The following will also be set or unset:
    #   arg_UNPARSED_ARGUMENTS
    #   arg_KEYWORDS_MISSING_VALUES

При использовании внутри макроса arg может быть неподходящим префиксом, потому что код повлияет на область вызова. Если другой макрос также вызывается в той же области, использовал бы arg в своём вызове cmake_parse_arguments(), и если у двух макросов есть общие ключевые слова, переменные последнего вызова могут перезаписывать или удалять переменные вызова предыдущего макроса. Поэтому рекомендуется включить в <prefix> что-то уникальное из имени макроса, например, arg_lowercase_macro_name.

macro(my_install)
    set(options OPTIONAL FAST)
    set(oneValueArgs DESTINATION RENAME)
    set(multiValueArgs TARGETS CONFIGURATIONS)
    cmake_parse_arguments(arg_my_install
        "${options}" "${oneValueArgs}" "${multiValueArgs}"
        ${ARGN}
    )
    # ...
endmacro()

macro(my_special_install)
    # NOTE: Has the same keywords as my_install()
    set(options OPTIONAL FAST)
    set(oneValueArgs DESTINATION RENAME)
    set(multiValueArgs TARGETS CONFIGURATIONS)
    cmake_parse_arguments(arg_my_special_install
        "${options}" "${oneValueArgs}" "${multiValueArgs}"
        ${ARGN}
    )
    # ...
endmacro()

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

my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS)
my_special_install(TARGETS barry DESTINATION sbin RENAME FAST)

После этих двух вызовов следующее описывает переменные, которые будут установлены или сброшены:

arg_my_install_OPTIONAL = TRUE
arg_my_install_FAST = FALSE # was not present in call to my_install
arg_my_install_DESTINATION = "bin"
arg_my_install_RENAME <UNSET> # was not present
arg_my_install_TARGETS = "foo;bar"
arg_my_install_CONFIGURATIONS <UNSET> # was not present
arg_my_install_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
arg_my_install_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS" # value was missing

arg_my_special_install_OPTIONAL = FALSE # was not present
arg_my_special_install_FAST = TRUE
arg_my_special_install_DESTINATION = "sbin"
arg_my_special_install_RENAME <UNSET> # value was missing
arg_my_special_install_TARGETS = "barry"
arg_my_special_install_CONFIGURATIONS <UNSET> # was not present
arg_my_special_install_UNPARSED_ARGUMENTS <UNSET>
arg_my_special_install_KEYWORDS_MISSING_VALUES = "RENAME"

Ключевые слова завершают списки значений. Если ключевое слово дано непосредственно после <one_value_keyword>, то предшествующее <one_value_keyword> не получит значения, и ключевое слово будет добавлено в переменную <prefix>_KEYWORDS_MISSING_VALUES. В приведённом примере вызов my_special_install() содержит ключевое слово RENAME, непосредственно за которым следует ключевое слово FAST. В этом случае FAST прекращает обработку ключевого слова RENAME. arg_my_special_install_FAST устанавливается в TRUE, arg_my_special_install_RENAME сбрасывается, и arg_my_special_install_KEYWORDS_MISSING_VALUES содержит значение RENAME.

См. также

• function()
• macro()