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

Added in version 3.5: 此命令已本机实现。以前，它是在模块 CMakeParseArguments 中定义的。

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

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

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

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

的 <one_value_keywords> 参数包含该函数或宏后面跟着一个值的关键字，例如 install() 命令的 DESTINATION 关键字。

的 <multi_value_keywords> 参数包含该函数或宏后面可以跟着多个值的关键字，例如 install() 命令的 TARGETS 或 FILES 关键字。

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

完成后，cmake_parse_arguments 将为 <options>、<one_value_keywords> 和 <multi_value_keywords> 中列出的每个关键字，创建一个由给定的 <prefix> 加上 "_" 和 respective 关键字名称组成的变量。对于 <one_value_keywords> 和 <multi_value_keywords>，这些变量将包含参数列表中的 respective 值，如果未提供关联关键字，则为空（策略 CMP0174 也会影响 <one_value_keywords> 的行为）。对于 <options> 关键字，这些变量将始终被定义，如果关键字存在，则设置为 TRUE，如果不存在，则设置为 FALSE。

所有剩余的参数都将收集到一个变量 <prefix>_UNPARSED_ARGUMENTS 中，如果所有参数都被识别，该变量将为空。之后可以检查此变量，以查看您的宏或函数是否使用了未识别的参数调用。

Added in version 3.15: 未提供任何值的 <one_value_keywords> 和 <multi_value_keywords> 将收集到一个变量 <prefix>_KEYWORDS_MISSING_VALUES 中，如果所有关键字都收到了值，则该变量将为空。可以检查此变量，以查看是否有关键字未提供值。

Changed in version 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。

另请参阅