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> 參數包含各函數或巨集的所有選項。這些是沒有後續值的關鍵字，例如 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> 後接 "_" 和各關鍵字名稱組成的變數。對於 <one_value_keywords> 和 <multi_value_keywords>，這些變數將保存來自參數列表的各值，或者如果未給定相關的關鍵字，則為未定義（策略 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。

參見