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()