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。

參見