FindPackageHandleStandardArgs

此模組提供在實作 Find Modules 時使用的函式，以處理 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。可能會根據結果以及是否給 find_package() 呼叫提供了 REQUIRED 和/或 QUIET 選項，顯示成功或失敗訊息。

選項如下

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

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

FOUND_VAR <結果變數>

自 3.3 版本起已棄用。

指定 <PackageName>_FOUND 或 <PACKAGENAME>_FOUND 作為結果變數。這僅為了與舊版 CMake 相容而存在，現在已被忽略。為了相容性，始終會設定兩個名稱的結果變數。

REQUIRED_VARS <必要變數>...

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

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

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 <失敗原因訊息>

在 3.16 版本中新增。

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

FAIL_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，則會失敗並顯示 message(FATAL_ERROR)，無論是否使用了 QUIET。如果找到，則將報告成功，包括第一個 <required-var> 的內容。在重複的 CMake 執行中，將不會再次列印相同的訊息。

注意

如果呼叫模組的 <PackageName> 與 CMAKE_FIND_PACKAGE_NAME 不符，則會發出警告，指出存在不符。如果使用舊簽名，則可以設定 FPHSA_NAME_MISMATCHED 變數來繞過警告，如果使用新簽名，則可以設定 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>]
  )

<結果變數> 將保存一個布林值，提供檢查的結果。

選項如下

HANDLE_VERSION_RANGE

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

RESULT_MESSAGE_VARIABLE <訊息變數>

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

使用範例

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