find_package ¶

注意

使用依賴關係指南 提供了此一般主題的高階介紹。它提供了 find_package() 命令在整體中的定位的更廣泛概述，包括其與 FetchContent 模組的關係。建議在繼續下面的詳細內容之前先閱讀本指南。

尋找套件（通常由專案外部的東西提供），並載入其套件特定的詳細資訊。對此命令的呼叫也可以被依賴關係提供者攔截。

典型用法 ¶

大多數對 find_package() 的呼叫通常具有以下形式

find_package(<PackageName> [<version>] [REQUIRED] [COMPONENTS <components>...])

<PackageName> 是唯一強制性的引數。<version> 通常會省略，如果專案在沒有套件的情況下無法成功配置，則應給定 REQUIRED。一些更複雜的套件支援可以使用 COMPONENTS 關鍵字選擇的元件，但大多數套件沒有那麼複雜的層級。

以上是基本簽名的簡化形式。在可能的情況下，專案應使用此形式尋找套件。這可以降低複雜性，並最大化尋找或提供套件的方式。

了解基本簽名應該足以用於 find_package() 的一般用法。打算提供配置套件的專案維護者應了解全局，如完整簽名和此頁面上的所有後續章節中所述。

搜尋模式 ¶

此命令具有幾種搜尋套件的模式

模組模式

在此模式下，CMake 會搜尋名為 Find<PackageName>.cmake 的檔案，首先在 CMAKE_MODULE_PATH 中列出的位置中查找，然後在 CMake 安裝提供的尋找模組中查找。如果找到該檔案，CMake 會讀取並處理它。它負責尋找套件、檢查版本並產生任何需要的訊息。一些 Find 模組對版本控制提供有限或不支援；請檢查 Find 模組的文件。

Find<PackageName>.cmake 檔案通常不是由套件本身提供。相反，它通常由套件外部的東西提供，例如作業系統、CMake 本身，甚至呼叫 find_package() 命令的專案。由於是外部提供的，尋找模組往往具有啟發式的本質，並且容易過時。它們通常會搜尋特定的程式庫、檔案和其他套件成品。

只有基本命令簽名支援模組模式。

配置模式

在此模式下，CMake 會搜尋名為 <lowercasePackageName>-config.cmake 或 <PackageName>Config.cmake 的檔案。如果指定了版本詳細資訊，它還會查找 <lowercasePackageName>-config-version.cmake 或 <PackageName>ConfigVersion.cmake（請參閱配置模式版本選擇，以了解如何使用這些單獨的版本檔案）。

在配置模式下，可以給定此命令要搜尋的名稱清單作為套件名稱。CMake 搜尋配置和版本檔案的位置比模組模式複雜得多（請參閱配置模式搜尋程序）。

配置和版本檔案通常會作為套件的一部分安裝，因此它們往往比尋找模組更可靠。它們通常包含套件內容的直接知識，因此在配置或版本檔案本身內不需要搜尋或啟發式。

基本和完整命令簽名都支援配置模式。

FetchContent 重新導向模式

在 3.24 版本中新增：對 find_package() 的呼叫可以在內部重新導向到由 FetchContent 模組提供的套件。對於呼叫者，行為將與配置模式類似，只是搜尋邏輯被略過且不使用元件資訊。有關詳細資訊，請參閱 FetchContent_Declare() 和 FetchContent_MakeAvailable()。

當未重新導向到由 FetchContent 提供的套件時，命令引數會決定是否使用模組或配置模式。使用基本簽名時，命令會先在模組模式中搜尋。如果找不到套件，則搜尋會退回配置模式。使用者可以將 CMAKE_FIND_PACKAGE_PREFER_CONFIG 變數設定為 true，以反轉優先順序並指示 CMake 先使用配置模式搜尋，然後再退回模組模式。基本簽名也可以使用 MODULE 關鍵字強制僅使用模組模式。如果使用完整簽名，則命令只會在配置模式中搜尋。

基本簽名 ¶

find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
             [REQUIRED] [[COMPONENTS] [components...]]
             [OPTIONAL_COMPONENTS components...]
             [REGISTRY_VIEW  (64|32|64_32|32_64|HOST|TARGET|BOTH)]
             [GLOBAL]
             [NO_POLICY_SCOPE]
             [BYPASS_PROVIDER])

模組和配置模式都支援基本簽名。MODULE 關鍵字表示只能使用模組模式來尋找套件，而不會退回配置模式。

無論使用哪種模式，都會設定 <PackageName>_FOUND 變數來指示是否找到套件。找到套件後，可能會透過其他變數和套件本身記錄的匯入目標來提供套件特定的資訊。QUIET 選項會停用資訊訊息，包括那些指示如果套件不是 REQUIRED 就找不到套件的訊息。REQUIRED 選項會在找不到套件時停止處理並顯示錯誤訊息。

在 COMPONENTS 關鍵字之後，可以列出套件特定的必要元件清單。如果無法滿足這些元件中的任何一個，則整體上會認為找不到套件。如果也存在 REQUIRED 選項，則會將其視為致命錯誤，否則執行仍會繼續。作為一種簡寫形式，如果存在 REQUIRED 選項，則可以省略 COMPONENTS 關鍵字，並且可以在 REQUIRED 之後直接列出必要的元件。

額外的可選元件可以在 OPTIONAL_COMPONENTS 之後列出。如果無法滿足這些元件，只要滿足所有必要元件，仍然可以認為整體上找到套件。

可用元件的集合及其含義由目標套件定義。形式上，由目標套件決定如何解釋提供給它的元件資訊，但它應遵循上述預期。對於未指定元件的呼叫，沒有單一的預期行為，並且目標套件應清楚地定義在這種情況下會發生什麼。常見的安排包括假設它應該尋找所有元件、不尋找任何元件或尋找一些明確定義的可用元件子集。

在 3.24 版本中新增：REGISTRY_VIEW 關鍵字指定應查詢哪些登錄檢視。此關鍵字僅在 Windows 平台上才有意義，在所有其他平台上都會被忽略。形式上，由目標套件決定如何解釋提供給它的登錄檢視資訊。

在 3.24 版本中新增：指定 GLOBAL 關鍵字會將所有匯入的目標提升到匯入專案中的全域範圍。或者，可以透過設定 CMAKE_FIND_PACKAGE_TARGETS_GLOBAL 變數來啟用此功能。

[version] 引數要求與找到的套件相容的版本。它可以使用兩種可能的形式指定

具有 major[.minor[.patch[.tweak]]] 格式的單一版本，其中每個元件都是數值。

版本範圍的格式為 versionMin...[<]versionMax，其中 versionMin 和 versionMax 的格式相同，並且對於組件的整數約束與單一版本相同。預設情況下，兩個端點都包含在內。透過指定 <，則會排除上限端點。版本範圍僅在 CMake 3.19 或更高版本中支援。

EXACT 選項要求版本必須完全匹配。此選項與指定版本範圍不相容。

如果在 find-module 內部的遞迴呼叫中沒有給定 [version] 和/或組件列表，則對應的引數會自動從外部呼叫轉發（包括 [version] 的 EXACT 標誌）。目前僅在逐個套件的基礎上提供版本支援（請參閱下方版本選擇章節）。當指定版本範圍，但套件僅設計為預期單一版本時，套件將忽略範圍的上限端點，僅考慮範圍下限的單一版本。

請參閱 cmake_policy() 命令文件，以了解 NO_POLICY_SCOPE 選項的討論。

在 3.24 版本中新增： BYPASS_PROVIDER 關鍵字僅在 find_package() 被相依性提供者呼叫時允許使用。提供者可以使用它直接呼叫內建的 find_package() 實作，並防止該呼叫重新路由回自身。未來版本的 CMake 可能會偵測到從相依性提供者以外的地方嘗試使用此關鍵字，並以嚴重錯誤中止。

完整簽名 ¶

find_package(<PackageName> [version] [EXACT] [QUIET]
             [REQUIRED] [[COMPONENTS] [components...]]
             [OPTIONAL_COMPONENTS components...]
             [CONFIG|NO_MODULE]
             [GLOBAL]
             [NO_POLICY_SCOPE]
             [BYPASS_PROVIDER]
             [NAMES name1 [name2 ...]]
             [CONFIGS config1 [config2 ...]]
             [HINTS path1 [path2 ... ]]
             [PATHS path1 [path2 ... ]]
             [REGISTRY_VIEW  (64|32|64_32|32_64|HOST|TARGET|BOTH)]
             [PATH_SUFFIXES suffix1 [suffix2 ...]]
             [NO_DEFAULT_PATH]
             [NO_PACKAGE_ROOT_PATH]
             [NO_CMAKE_PATH]
             [NO_CMAKE_ENVIRONMENT_PATH]
             [NO_SYSTEM_ENVIRONMENT_PATH]
             [NO_CMAKE_PACKAGE_REGISTRY]
             [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
             [NO_CMAKE_SYSTEM_PATH]
             [NO_CMAKE_INSTALL_PREFIX]
             [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
             [CMAKE_FIND_ROOT_PATH_BOTH |
              ONLY_CMAKE_FIND_ROOT_PATH |
              NO_CMAKE_FIND_ROOT_PATH])

CONFIG 選項、同義詞 NO_MODULE 選項或使用基本簽名中未指定的選項都會強制執行純粹的 Config 模式。在純粹的 Config 模式中，該命令會跳過 Module 模式搜尋，並立即進行 Config 模式搜尋。

Config 模式搜尋嘗試尋找要尋找的套件提供的組態檔。建立一個名為 <PackageName>_DIR 的快取項目，以保留包含該檔案的目錄。預設情況下，該命令會搜尋名為 <PackageName> 的套件。如果給定 NAMES 選項，則會使用其後的名稱來取代 <PackageName>。在決定是否將呼叫重新導向到 FetchContent 提供的套件時，也會考慮這些名稱。

該命令會針對指定的每個名稱搜尋名為 <PackageName>Config.cmake 或 <lowercasePackageName>-config.cmake 的檔案。可以使用 CONFIGS 選項給定一組替換的可能組態檔名。以下指定了 Config 模式搜尋程序。一旦找到，則會檢查任何版本限制，如果滿足條件，CMake 會讀取並處理組態檔。由於該檔案是由套件提供的，因此它已經知道套件內容的位置。組態檔的完整路徑會儲存在 CMake 變數 <PackageName>_CONFIG 中。

CMake 在搜尋具有適當版本的套件時所考慮的所有組態檔都儲存在 <PackageName>_CONSIDERED_CONFIGS 變數中，而相關的版本則儲存在 <PackageName>_CONSIDERED_VERSIONS 變數中。

如果找不到套件組態檔，CMake 將產生一個描述問題的錯誤，除非指定了 QUIET 引數。如果指定了 REQUIRED，但找不到套件，則會產生嚴重錯誤，並停止執行組態步驟。如果 <PackageName>_DIR 已設定為不包含組態檔的目錄，CMake 將忽略它並從頭開始搜尋。

建議提供 CMake 套件組態檔的套件維護人員對其進行命名和安裝，以便以下概述的 Config 模式搜尋程序無需使用其他選項即可找到它們。

Config 模式搜尋程序 ¶

注意

當使用 Config 模式時，無論是給定完整簽名還是基本簽名，都會應用此搜尋程序。

在 3.24 版本中新增：所有對 find_package() 的呼叫（即使在 Module 模式中）都會先在 CMAKE_FIND_PACKAGE_REDIRECTS_DIR 目錄中尋找組態套件檔。FetchContent 模組，甚至是專案本身，都可以將檔案寫入該位置，以將 find_package() 呼叫重新導向到專案已提供的內容。如果該位置找不到組態套件檔，則搜尋會繼續使用以下描述的邏輯。

CMake 會為套件建構一組可能的安裝前置詞。在每個前置詞下，都會搜尋數個目錄以尋找組態檔。下表顯示了搜尋的目錄。每個項目都適用於遵循 Windows (W)、UNIX (U) 或 Apple (A) 約定的安裝樹狀結構。

項目	約定
`<prefix>/`	W
`<prefix>/(cmake\|CMake)/`	W
`<prefix>/<name>*/`	W
`<prefix>/<name>*/(cmake\|CMake)/`	W
`<prefix>/<name>/(cmake\|CMake)/<name>/` [1]	W
`<prefix>/(lib/<arch>\|lib\|share)/cmake/<name>/`	U
`<prefix>/(lib/<arch>\|lib\|share)/<name>/`	U
`<prefix>/(lib/<arch>\|lib\|share)/<name>/(cmake\|CMake)/`	U
`<prefix>/<name>/(lib/<arch>\|lib\|share)/cmake/<name>*/`	W/U
`<prefix>/<name>/(lib/<arch>\|lib\|share)/<name>*/`	W/U
`<prefix>/<name>/(lib/<arch>\|lib\|share)/<name>*/(cmake\|CMake)/`	W/U

在支援 macOS FRAMEWORK 和 BUNDLE 的系統上，會在以下目錄中搜尋包含組態檔的 Frameworks 或應用程式套件組合

項目	約定
`<prefix>/<name>.framework/Resources/`	A
`<prefix>/<name>.framework/Resources/CMake/`	A
`<prefix>/<name>.framework/Versions/*/Resources/`	A
`<prefix>/<name>.framework/Versions/*/Resources/CMake/`	A
`<prefix>/<name>.app/Contents/Resources/`	A
`<prefix>/<name>.app/Contents/Resources/CMake/`	A

在所有情況下，<name> 都會被視為不區分大小寫，並且對應於指定的任何名稱（<PackageName> 或 NAMES 給定的名稱）。

如果至少啟用了一種已編譯的語言，則可能會根據編譯器的目標架構，依以下順序搜尋特定於架構的 lib/<arch> 和 lib* 目錄

lib/<arch>: 如果設定了 CMAKE_LIBRARY_ARCHITECTURE 變數，則會搜尋。
lib64: 在 64 位元平台上搜尋（CMAKE_SIZEOF_VOID_P 為 8），並且 FIND_LIBRARY_USE_LIB64_PATHS 屬性設定為 TRUE。
lib32: 在 32 位元平台上搜尋（CMAKE_SIZEOF_VOID_P 為 4），且 FIND_LIBRARY_USE_LIB32_PATHS 屬性設定為 TRUE。
libx32: 如果 FIND_LIBRARY_USE_LIBX32_PATHS 屬性設定為 TRUE，則會在使用 x32 ABI 的平台上搜尋。
lib: 永遠搜尋。

在 3.24 版本變更：在 Windows 平台上，可以使用專用語法，將登錄檔查詢包含在透過 HINTS 和 PATHS 關鍵字指定的目錄中。此類規格將在所有其他平台上被忽略。

在 3.24 版本新增：可以指定 REGISTRY_VIEW 來管理在 PATHS 和 HINTS 中指定的 Windows 登錄檔查詢。

指定必須查詢哪個登錄檔檢視。此選項僅在 Windows 平台上才有意義，在其他平台上將被忽略。未指定時，當 CMP0134 政策為 NEW 時，將使用 TARGET 檢視。當政策為 OLD 時，請參考 CMP0134 以瞭解預設檢視。

64

查詢 64 位元登錄檔。在 32 位元 Windows 上，它總是會傳回字串 /REGISTRY-NOTFOUND。

32

查詢 32 位元登錄檔。

64_32

查詢兩種檢視（64 和 32），並為每個檢視產生一個路徑。

32_64

查詢兩種檢視（32 和 64），並為每個檢視產生一個路徑。

HOST

查詢符合主機架構的登錄檔：64 位元 Windows 上為 64，32 位元 Windows 上為 32。

TARGET

查詢符合 CMAKE_SIZEOF_VOID_P 變數指定的架構的登錄檔。如果未定義，則會回退到 HOST 檢視。

BOTH

查詢兩種檢視（32 和 64）。順序取決於以下規則：如果定義了 CMAKE_SIZEOF_VOID_P 變數，則根據此變數的內容使用以下檢視

8: 64_32
4: 32_64

如果未定義 CMAKE_SIZEOF_VOID_P 變數，則依賴主機的架構

64 位元：64_32
32 位元：32

如果指定了 PATH_SUFFIXES，則會將後綴逐一附加到每個 (W) 或 (U) 目錄條目。

此目錄集旨在與在其安裝樹中提供組態檔案的專案協同運作。標記為 (W) 的以上目錄適用於 Windows 上的安裝，其中前綴可能指向應用程式安裝目錄的頂部。標記為 (U) 的目錄適用於 UNIX 平台上的安裝，其中前綴由多個套件共用。這僅是一種慣例，因此仍然會在所有平台上搜尋所有 (W) 和 (U) 目錄。標記為 (A) 的目錄適用於 Apple 平台上的安裝。CMAKE_FIND_FRAMEWORK 和 CMAKE_FIND_APPBUNDLE 變數決定優先順序。

安裝前綴集是使用以下步驟建構的。如果指定 NO_DEFAULT_PATH，則會啟用所有 NO_* 選項。

搜尋目前正在尋找的 <PackageName> 的專屬前綴。請參閱政策 CMP0074。

在 3.12 版本中新增。

具體而言，依序搜尋以下變數指定的前綴
1. <PackageName>_ROOT CMake 變數，其中 <PackageName> 是保留大小寫的套件名稱。
2. <PACKAGENAME>_ROOT CMake 變數，其中 <PACKAGENAME> 是大寫的套件名稱。請參閱政策 CMP0144。
  
  在 3.27 版本中新增。
3. <PackageName>_ROOT 環境變數，其中 <PackageName> 是保留大小寫的套件名稱。
4. <PACKAGENAME>_ROOT 環境變數，其中 <PACKAGENAME> 是大寫的套件名稱。請參閱政策 CMP0144。
  
  在 3.27 版本中新增。
套件根目錄變數會維護為堆疊，因此如果從 find 模組內呼叫，也會在目前套件的路徑之後搜尋父 find 模組的根路徑。如果傳遞 NO_PACKAGE_ROOT_PATH 或將 CMAKE_FIND_USE_PACKAGE_ROOT_PATH 設定為 FALSE，則可以略過此操作。
搜尋在 cmake 專用快取變數中指定的路徑。這些變數旨在與命令列上的 -DVAR=VALUE 一起使用。這些值會被解讀為分號分隔的清單。如果傳遞 NO_CMAKE_PATH 或將 CMAKE_FIND_USE_CMAKE_PATH 設定為 FALSE，則可以略過此操作
在 CMake 專屬的環境變數中指定的搜尋路徑。這些變數通常設定在使用者的 shell 設定中，因此使用主機的原生路徑分隔符（Windows 上為 ;，UNIX 上為 :）。如果傳遞 NO_CMAKE_ENVIRONMENT_PATH 或將 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH 設定為 FALSE，則可以跳過此步驟。
- <PackageName>_DIR
- CMAKE_PREFIX_PATH
- CMAKE_FRAMEWORK_PATH
- CMAKE_APPBUNDLE_PATH
由 HINTS 選項指定的搜尋路徑。這些應該是由系統內省計算的路徑，例如已經找到的另一個項目的位置所提供的提示。硬編碼的猜測應使用 PATHS 選項指定。
搜尋標準系統環境變數。如果傳遞 NO_SYSTEM_ENVIRONMENT_PATH 或將 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH 設定為 FALSE，則可以跳過此步驟。以 /bin 或 /sbin 結尾的路徑條目會自動轉換為其父目錄。
- PATH
搜尋儲存在 CMake 使用者套件註冊表中的路徑。如果傳遞 NO_CMAKE_PACKAGE_REGISTRY 或將變數 CMAKE_FIND_USE_PACKAGE_REGISTRY 設定為 FALSE 或將已棄用的變數 CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY 設定為 TRUE，則可以跳過此步驟。

有關使用者套件註冊表的詳細資訊，請參閱 cmake-packages(7) 手冊。
搜尋為目前系統在平台檔案中定義的 CMake 變數。如果傳遞 NO_CMAKE_INSTALL_PREFIX 或將 CMAKE_FIND_USE_INSTALL_PREFIX 設定為 FALSE，則可以跳過搜尋 CMAKE_INSTALL_PREFIX 和 CMAKE_STAGING_PREFIX。如果傳遞 NO_CMAKE_SYSTEM_PATH 或將 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH 設定為 FALSE，則可以跳過所有這些位置。
這些變數包含的平台路徑是通常包含已安裝軟體的位置。例如，UNIX 基礎的平台為 /usr/local。
搜尋儲存在 CMake 系統套件註冊表中的路徑。如果傳遞 NO_CMAKE_SYSTEM_PACKAGE_REGISTRY 或將變數 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY 設定為 FALSE 或將已棄用的變數 CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY 設定為 TRUE，則可以跳過此步驟。

有關系統套件註冊表的詳細資訊，請參閱 cmake-packages(7) 手冊。
由 PATHS 選項指定的搜尋路徑。這些通常是硬編碼的猜測。

CMAKE_IGNORE_PATH、CMAKE_IGNORE_PREFIX_PATH、CMAKE_SYSTEM_IGNORE_PATH 和 CMAKE_SYSTEM_IGNORE_PREFIX_PATH 變數也可能會導致忽略上述某些位置。

路徑會依上述順序搜尋。找到的第一個可行的套件組態檔案會被使用，即使套件的較新版本位於搜尋路徑清單的稍後位置。

對於包含 <name>* 的搜尋路徑，除非設定了 CMAKE_FIND_PACKAGE_SORT_ORDER 變數，否則匹配路徑之間的順序是未指定的。此變數以及 CMAKE_FIND_PACKAGE_SORT_DIRECTION 變數，決定 CMake 考量符合包含 <name>* 的單一搜尋路徑的路徑的順序。例如，如果檔案系統包含套件組態檔案

<prefix>/example-1.2/example-config.cmake
<prefix>/example-1.10/example-config.cmake
<prefix>/share/example-2.0/example-config.cmake

當上述變數未設定時，find_package(example) 是否會找到 example-1.2 或 example-1.10 (假設兩者都是可行的) 是未指定的，但 find_package 將不會找到 example-2.0，因為將首先找到其他兩個之一。

若要控制 find_package 搜尋符合 glob 運算式的目錄的順序，請使用 CMAKE_FIND_PACKAGE_SORT_ORDER 和 CMAKE_FIND_PACKAGE_SORT_DIRECTION。例如，要讓上述範例選取 example-1.10，可以設定

SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)

在呼叫 find_package 之前。

在 3.16 版本中新增：新增 CMAKE_FIND_USE_<CATEGORY> 變數以全域停用各種搜尋位置。

CMake 變數 CMAKE_FIND_ROOT_PATH 指定一個或多個要附加到所有其他搜尋目錄的路徑。這會有效地將整個搜尋「重新紮根」到給定的位置下。屬於 CMAKE_STAGING_PREFIX 的子路徑會被排除在此重新紮根之外，因為該變數始終是主機系統上的路徑。預設情況下，CMAKE_FIND_ROOT_PATH 為空。

CMAKE_SYSROOT 變數也可用於指定一個確切的目錄作為前置詞。設定 CMAKE_SYSROOT 也有其他影響。請參閱該變數的文件以了解更多資訊。

這些變數在交叉編譯時特別有用，可以指向目標環境的根目錄，而 CMake 也會在那裡搜尋。預設情況下，首先會搜尋 CMAKE_FIND_ROOT_PATH 中列出的目錄，然後搜尋 CMAKE_SYSROOT 目錄，然後搜尋非根目錄。預設行為可以透過設定 CMAKE_FIND_ROOT_PATH_MODE_PACKAGE 來調整。此行為可以在每次呼叫時使用選項手動覆寫

CMAKE_FIND_ROOT_PATH_BOTH: 按照上述順序搜尋。
NO_CMAKE_FIND_ROOT_PATH: 不使用 CMAKE_FIND_ROOT_PATH 變數。
ONLY_CMAKE_FIND_ROOT_PATH: 僅搜尋重新紮根的目錄和 CMAKE_STAGING_PREFIX 下的目錄。

預設搜尋順序旨在針對常見用例，從最特定到最不特定。專案可以簡單地多次呼叫命令並使用 NO_* 選項來覆寫順序

find_package (<PackageName> PATHS paths... NO_DEFAULT_PATH)
find_package (<PackageName>)

一旦其中一個呼叫成功，結果變數將被設定並儲存在快取中，因此不會再次搜尋。

預設情況下，儲存在結果變數中的值將是找到檔案的路徑。可以在呼叫 find_package 之前將 CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS 變數設定為 TRUE，以便解析符號連結並儲存檔案的實際路徑。

每個非 REQUIRED 的 find_package 呼叫都可以停用或設為 REQUIRED

將 CMAKE_DISABLE_FIND_PACKAGE_<PackageName> 變數設定為 TRUE 會停用該套件。這也會停用重新導向到 FetchContent 提供的套件。
將 CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> 變數設定為 TRUE 會使該套件成為 REQUIRED。

同時將兩個變數都設定為 TRUE 是一個錯誤。

Config 模式版本選擇 ¶

注意

當使用 Config 模式時，無論給定的是完整還是基本簽名，都會套用此版本選擇程序。

當給定 [version] 引數時，Config 模式只會找到聲稱與請求版本相容的套件版本（請參閱格式規格）。如果給定 EXACT 選項，則只會找到聲稱與請求版本完全匹配的套件版本。CMake 沒有為版本號碼的含義建立任何慣例。套件版本號碼由套件本身提供的「版本」檔案或 FetchContent 檢查。對於候選套件組態檔案 <config-file>.cmake，對應的版本檔案位於其旁邊，並命名為 <config-file>-version.cmake 或 <config-file>Version.cmake。如果沒有此類版本檔案，則假定組態檔案與任何請求的版本不相容。可以使用 CMakePackageConfigHelpers 模組建立包含通用版本匹配程式碼的基本版本檔案。當找到版本檔案時，會載入該檔案以檢查請求的版本號碼。版本檔案會在已定義下列變數的巢狀範圍中載入

PACKAGE_FIND_NAME: <PackageName>
PACKAGE_FIND_VERSION: 完整的請求版本字串
PACKAGE_FIND_VERSION_MAJOR: 如果已請求，則為主要版本，否則為 0
PACKAGE_FIND_VERSION_MINOR: 如果已請求，則為次要版本，否則為 0
PACKAGE_FIND_VERSION_PATCH: 如果已請求，則為修補版本，否則為 0
PACKAGE_FIND_VERSION_TWEAK: 如果已請求，則為調整版本，否則為 0
PACKAGE_FIND_VERSION_COUNT: 版本元件的數量，0 到 4

當指定版本範圍時，上述版本變數將保留基於版本範圍下限的值。這是為了保持與尚未實作以預期版本範圍的套件的相容性。此外，版本範圍將由下列變數描述

PACKAGE_FIND_VERSION_RANGE: 完整的請求版本範圍字串
PACKAGE_FIND_VERSION_RANGE_MIN: 這指定是否應包含或排除版本範圍的下限端點。目前，此變數唯一支援的值是 INCLUDE。
PACKAGE_FIND_VERSION_RANGE_MAX: 這指定是否應包含或排除版本範圍的上限端點。此變數支援的值為 INCLUDE 和 EXCLUDE。
PACKAGE_FIND_VERSION_MIN: 範圍下限端點的完整請求版本字串
PACKAGE_FIND_VERSION_MIN_MAJOR: 如果已請求，則為下限端點的主要版本，否則為 0
PACKAGE_FIND_VERSION_MIN_MINOR: 如果已請求，則為下限端點的次要版本，否則為 0
PACKAGE_FIND_VERSION_MIN_PATCH: 如果已請求，則為下限端點的修補版本，否則為 0
PACKAGE_FIND_VERSION_MIN_TWEAK: 如果已請求，則為下限端點的調整版本，否則為 0
PACKAGE_FIND_VERSION_MIN_COUNT: 下限端點的版本元件數量，0 到 4
PACKAGE_FIND_VERSION_MAX: 範圍上限端點的完整請求版本字串
PACKAGE_FIND_VERSION_MAX_MAJOR: 如果已請求，則為上限端點的主要版本，否則為 0
PACKAGE_FIND_VERSION_MAX_MINOR: 如果已請求，則為上限端點的次要版本，否則為 0
PACKAGE_FIND_VERSION_MAX_PATCH: 如果已請求，則為上限端點的修補版本，否則為 0
PACKAGE_FIND_VERSION_MAX_TWEAK: 如果已請求，則為上限端點的調整版本，否則為 0
PACKAGE_FIND_VERSION_MAX_COUNT: 上限端點的版本元件數量，0 到 4

無論是指定單個版本還是版本範圍，都將定義變數 PACKAGE_FIND_VERSION_COMPLETE，並且將保留指定的完整請求版本字串。

版本檔案會檢查它是否滿足請求的版本，並設定這些變數

PACKAGE_VERSION: 完整的版本字串
PACKAGE_VERSION_EXACT: 若版本完全符合則為 True
PACKAGE_VERSION_COMPATIBLE: 若版本相容則為 True
PACKAGE_VERSION_UNSUITABLE: 若任何版本都不適合則為 True

這些變數由 find_package 命令檢查，以判斷組態檔是否提供可接受的版本。它們在 find_package 呼叫返回後不可用。如果版本可接受，則會設定以下變數

<PackageName>_VERSION: 完整的版本字串
<PackageName>_VERSION_MAJOR: 如果提供則為主要版本，否則為 0
<PackageName>_VERSION_MINOR: 如果提供則為次要版本，否則為 0
<PackageName>_VERSION_PATCH: 如果提供則為修補版本，否則為 0
<PackageName>_VERSION_TWEAK: 如果提供則為微調版本，否則為 0
<PackageName>_VERSION_COUNT: 版本元件的數量，0 到 4

並且載入相應的套件組態檔。

套件檔案介面變數 ¶

當載入 find 模組或套件組態檔時，find_package 會定義變數來提供關於呼叫參數的資訊 (並在返回前恢復它們的原始狀態)

CMAKE_FIND_PACKAGE_NAME: 所搜尋的 <PackageName>
<PackageName>_FIND_REQUIRED: 如果給定了 REQUIRED 選項則為 True
<PackageName>_FIND_QUIETLY: 如果給定了 QUIET 選項則為 True
<PackageName>_FIND_REGISTRY_VIEW: 如果給定了 REGISTRY_VIEW 選項則為請求的視圖
<PackageName>_FIND_VERSION: 完整的請求版本字串
<PackageName>_FIND_VERSION_MAJOR: 如果已請求，則為主要版本，否則為 0
<PackageName>_FIND_VERSION_MINOR: 如果已請求，則為次要版本，否則為 0
<PackageName>_FIND_VERSION_PATCH: 如果已請求，則為修補版本，否則為 0
<PackageName>_FIND_VERSION_TWEAK: 如果已請求，則為調整版本，否則為 0
<PackageName>_FIND_VERSION_COUNT: 版本元件的數量，0 到 4
<PackageName>_FIND_VERSION_EXACT: 如果給定了 EXACT 選項則為 True
<PackageName>_FIND_COMPONENTS: 指定的組件列表 (必要和可選)
<PackageName>_FIND_REQUIRED_<c>: 如果組件 <c> 是必要的，則為 True，如果組件 <c> 是可選的，則為 false

當指定版本範圍時，上述版本變數將保留基於版本範圍下限的值。這是為了保持與尚未實作以預期版本範圍的套件的相容性。此外，版本範圍將由下列變數描述

<PackageName>_FIND_VERSION_RANGE: 完整的請求版本範圍字串
<PackageName>_FIND_VERSION_RANGE_MIN: 這指定版本範圍的下限是否包含或排除。目前，INCLUDE 是唯一支援的值。
<PackageName>_FIND_VERSION_RANGE_MAX: 這指定版本範圍的上限是否包含或排除。此變數的可能值為 INCLUDE 或 EXCLUDE。
<PackageName>_FIND_VERSION_MIN: 範圍下限端點的完整請求版本字串
<PackageName>_FIND_VERSION_MIN_MAJOR: 如果已請求，則為下限端點的主要版本，否則為 0
<PackageName>_FIND_VERSION_MIN_MINOR: 如果已請求，則為下限端點的次要版本，否則為 0
<PackageName>_FIND_VERSION_MIN_PATCH: 如果已請求，則為下限端點的修補版本，否則為 0
<PackageName>_FIND_VERSION_MIN_TWEAK: 如果已請求，則為下限端點的調整版本，否則為 0
<PackageName>_FIND_VERSION_MIN_COUNT: 下限端點的版本元件數量，0 到 4
<PackageName>_FIND_VERSION_MAX: 範圍上限端點的完整請求版本字串
<PackageName>_FIND_VERSION_MAX_MAJOR: 如果已請求，則為上限端點的主要版本，否則為 0
<PackageName>_FIND_VERSION_MAX_MINOR: 如果已請求，則為上限端點的次要版本，否則為 0
<PackageName>_FIND_VERSION_MAX_PATCH: 如果已請求，則為上限端點的修補版本，否則為 0
<PackageName>_FIND_VERSION_MAX_TWEAK: 如果已請求，則為上限端點的調整版本，否則為 0
<PackageName>_FIND_VERSION_MAX_COUNT: 上限端點的版本元件數量，0 到 4

無論指定單一版本還是版本範圍，都會定義變數 <PackageName>_FIND_VERSION_COMPLETE，並且將保留指定的完整請求版本字串。

在模組模式下，載入的 find 模組負責遵循這些變數詳細說明的請求；請參閱 find 模組以了解詳細資訊。在組態模式下，find_package 會自動處理 REQUIRED、QUIET 和 [version] 選項，但會將組件的處理方式留給套件組態檔，使其對套件有意義。套件組態檔可能會將 <PackageName>_FOUND 設定為 false，以告知 find_package 組件需求未滿足。

項目	約定
`<prefix>/`	W
`<prefix>/(cmake\|CMake)/`	W
`<prefix>/<name>*/`	W
`<prefix>/<name>*/(cmake\|CMake)/`	W
`<prefix>/<name>/(cmake\|CMake)/<name>/` [1]	W
`<prefix>/(lib/<arch>\|lib\|share)/cmake/<name>/`	U
`<prefix>/(lib/<arch>\|lib\|share)/<name>/`	U
`<prefix>/(lib/<arch>\|lib\|share)/<name>/(cmake\|CMake)/`	U
`<prefix>/<name>/(lib/<arch>\|lib\|share)/cmake/<name>*/`	W/U
`<prefix>/<name>/(lib/<arch>\|lib\|share)/<name>*/`	W/U
`<prefix>/<name>/(lib/<arch>\|lib\|share)/<name>*/(cmake\|CMake)/`	W/U

find_package ¶

典型用法 ¶

搜尋模式 ¶

基本簽名 ¶

完整簽名 ¶

Config 模式搜尋程序 ¶

Config 模式版本選擇 ¶

套件檔案介面變數 ¶

目錄

上一主題

下一主題

本頁