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

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