FindPackageHandleStandardArgs

此模組提供函數，旨在用於實作 find_package(<PackageName>) 呼叫的 尋找模組 中。

find_package_handle_standard_args

此命令處理 find_package() 的 REQUIRED、QUIET 和版本相關引數。它還設定 <PackageName>_FOUND 變數。如果列出的所有變數都包含有效結果（例如，有效檔案路徑），則該套件會被視為已找到。

有兩種簽名

find_package_handle_standard_args(<PackageName>
  (DEFAULT_MSG|<custom-failure-message>)
  <required-var>...
  )

find_package_handle_standard_args(<PackageName>
  [FOUND_VAR <result-var>]
  [REQUIRED_VARS <required-var>...]
  [VERSION_VAR <version-var>]
  [HANDLE_VERSION_RANGE]
  [HANDLE_COMPONENTS]
  [CONFIG_MODE]
  [NAME_MISMATCHED]
  [REASON_FAILURE_MESSAGE <reason-failure-message>]
  [FAIL_MESSAGE <custom-failure-message>]
  )

如果所有變數 <required-var>... 都有效，並且滿足任何可選約束，則 <PackageName>_FOUND 變數將設定為 TRUE，否則設定為 FALSE。可能會根據結果以及 REQUIRED 和/或 QUIET 選項是否給予 find_package() 呼叫來顯示成功或失敗訊息。

選項如下

(DEFAULT_MSG|<自訂失敗訊息>)

在簡單簽名中，這指定失敗訊息。使用 DEFAULT_MSG 要求計算預設訊息（建議）。在完整簽名中無效。

FOUND_VAR <result-var>

自版本 3.3 起已棄用。

指定 <PackageName>_FOUND 或 <PACKAGENAME>_FOUND 作為結果變數。這僅為了與舊版本的 CMake 相容而存在，現在已被忽略。現在始終設定這兩個名稱的結果變數，以與使用或不使用此選項的情況相容。

REQUIRED_VARS <required-var>...

指定此套件所需的變數。這些變數可能會在產生的失敗訊息中命名，要求使用者設定遺失的變數值。因此，這些通常應該是快取條目，例如 FOO_LIBRARY，而不是輸出變數，例如 FOO_LIBRARIES。

在版本 3.18 中變更：如果指定了 HANDLE_COMPONENTS，則可以省略此選項。

VERSION_VAR <version-var>

指定一個變數的名稱，該變數保存已找到的套件版本。將針對給予 find_package() 呼叫的（可能）指定的所需版本檢查此版本，包括其 EXACT 選項。預設訊息包含有關所需版本和實際找到的版本的資訊，無論版本是否正確。

HANDLE_VERSION_RANGE

在版本 3.19 中新增。

如果指定了版本範圍，則啟用版本範圍的處理。如果指定了版本範圍，則沒有此選項將顯示開發人員警告。

HANDLE_COMPONENTS

啟用套件組件的處理。在這種情況下，命令將報告已找到哪些組件和遺失哪些組件，並且如果任何必需組件（即，不是在 find_package() 的 OPTIONAL_COMPONENTS 選項之後列出的組件）遺失，則 <PackageName>_FOUND 變數將設定為 FALSE。

CONFIG_MODE

指定呼叫尋找模組是 find_package(<PackageName> NO_MODULE) 呼叫的包裝函式。這表示 VERSION_VAR 值為 <PackageName>_VERSION。命令將自動檢查是否找到了套件組態檔。

REASON_FAILURE_MESSAGE <reason-failure-message>

在版本 3.16 中新增。

指定失敗原因的自訂訊息，該訊息將附加到預設產生的訊息中。

FAIL_MESSAGE <custom-failure-message>

指定自訂失敗訊息，而不是使用預設產生的訊息。不建議使用。

NAME_MISMATCHED

在版本 3.17 中新增。

指示 <PackageName> 與 ${CMAKE_FIND_PACKAGE_NAME} 不符。這通常是一個錯誤並引發警告，但對於將命令用於較大套件的組件而言，這可能是故意的。

簡單簽名的範例

find_package_handle_standard_args(LibXml2 DEFAULT_MSG
  LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)

如果 LIBXML2_LIBRARY 和 LIBXML2_INCLUDE_DIR 都有效，則認為已找到 LibXml2 套件。然後，LibXml2_FOUND 也設定為 TRUE。如果未找到且使用了 REQUIRED，則無論是否使用了 QUIET，都會以 message(FATAL_ERROR) 失敗。如果找到，將報告成功，包括第一個 <required-var> 的內容。在重複的 CMake 執行中，不會再次列印相同的訊息。

注意

如果 <PackageName> 與呼叫模組的 CMAKE_FIND_PACKAGE_NAME 不符，則會發出警告，指出存在不符之處。如果使用舊簽名且未使用新簽名的 NAME_MISMATCHED 引數，則可以設定 FPHSA_NAME_MISMATCHED 變數以繞過警告。為了避免強制呼叫者要求較新版本的 CMake 以供使用，如果在使用新簽名時未傳遞 NAME_MISMATCHED 引數，則將使用該變數的值（但同時使用兩者是錯誤的）。

完整簽名的範例

find_package_handle_standard_args(LibArchive
  REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR
  VERSION_VAR LibArchive_VERSION)

在這種情況下，如果 LibArchive_LIBRARY 和 LibArchive_INCLUDE_DIR 都有效，則認為已找到 LibArchive 套件。此外，將透過使用 LibArchive_VERSION 中包含的版本來檢查 LibArchive 的版本。由於未給出 FAIL_MESSAGE，因此將列印預設訊息。

完整簽名的另一個範例

find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4)
find_package_handle_standard_args(Automoc4  CONFIG_MODE)

在這種情況下，FindAutmoc4.cmake 模組包裝了對 find_package(Automoc4 NO_MODULE) 的呼叫，並為 automoc4 新增了額外的搜尋目錄。然後，對 find_package_handle_standard_args 的呼叫會產生正確的成功/失敗訊息。

find_package_check_version

在版本 3.19 中新增。

輔助函數，可用於檢查 <version> 對 find_package() 的版本相關引數是否有效。

find_package_check_version(<version> <result-var>
  [HANDLE_VERSION_RANGE]
  [RESULT_MESSAGE_VARIABLE <message-var>]
  )

<result-var> 將保存一個布林值，給出檢查的結果。

選項如下

HANDLE_VERSION_RANGE

如果指定了版本範圍，則啟用版本範圍的處理。如果指定了版本範圍，則沒有此選項將顯示開發人員警告。

RESULT_MESSAGE_VARIABLE <message-var>

指定一個變數以取回描述檢查結果的訊息。

使用範例

find_package_check_version(1.2.3 result HANDLE_VERSION_RANGE
  RESULT_MESSAGE_VARIABLE reason)
if(result)
  message(STATUS "${reason}")
else()
  message(FATAL_ERROR "${reason}")
endif()