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

3.5 版本加入: 此命令为原生实现。 之前，它已经在模块 CMakeParseArguments 中定义。

此命令用于宏或函数中。 它处理传递给该宏或函数的参数，并定义一组变量，这些变量保存各个选项的值。

第一个签名读取在 <args>... 中传递的参数。 这可以在 macro() 或 function() 中使用。

3.7 版本加入: PARSE_ARGV 签名仅用于 function() 主体中。 在这种情况下，要解析的参数来自调用函数的 ARGV# 变量。 解析从第 <N> 个参数开始，其中 <N> 是一个无符号整数。 这允许值包含像 ; 这样的特殊字符。

<options> 参数包含各个函数或宏的所有选项。 这些是不带值的关键字，例如 install() 命令的 OPTIONAL 关键字。

<one_value_keywords> 参数包含此函数或宏的所有关键字，这些关键字后跟一个值，例如 install() 命令的 DESTINATION 关键字。

<multi_value_keywords> 参数包含此函数或宏的所有关键字，这些关键字后可跟多个值，例如 install() 命令的 TARGETS 或 FILES 关键字。

3.5 版本变更: 所有关键字必须是唯一的。 每个关键字在 <options>、<one_value_keywords> 或 <multi_value_keywords> 的任何一个中只能指定一次。 如果违反唯一性，将发出警告。

完成后，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 中，如果所有参数都被识别，则该变量将未定义。 之后可以检查此变量，以查看您的宏或函数是否使用无法识别的参数调用。

3.15 版本加入: 没有给定任何值的 <one_value_keywords> 和 <multi_value_keywords> 被收集在一个变量 <prefix>_KEYWORDS_MISSING_VALUES 中，如果所有关键字都收到值，则该变量将未定义。 可以检查此变量，以查看是否有关键字没有给定任何值。

3.31 版本变更: 如果 <one_value_keyword> 后跟一个空字符串作为其值，则策略 CMP0174 控制是否定义相应的 <prefix>_<keyword> 变量。

仔细选择 <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 可能不是合适的前缀，因为代码会影响调用范围。 如果在同一范围内调用的另一个宏也在其自身的 cmake_parse_arguments() 调用中使用 arg，并且如果两个宏之间有任何公共关键字，则稍后调用的变量可能会覆盖或删除早期宏调用的变量。 因此，建议在 <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()