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() 的调用紧随 FAST 关键字之后直接包含 RENAME 关键字。在这种情况下，FAST 终止对 RENAME 关键字的处理。将 arg_my_special_install_FAST 设置为 TRUE，取消设置 arg_my_special_install_RENAME，并且 arg_my_special_install_KEYWORDS_MISSING_VALUES 包含值 RENAME。

另请参见