find_library

簡短的語法是

find_library (<VAR> name1 [path1 path2 ...])

一般的語法是

find_library (
          <VAR>
          name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
          [HINTS [path | ENV var]... ]
          [PATHS [path | ENV var]... ]
          [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
          [PATH_SUFFIXES suffix1 [suffix2 ...]]
          [VALIDATOR function]
          [DOC "cache documentation string"]
          [NO_CACHE]
          [REQUIRED]
          [NO_DEFAULT_PATH]
          [NO_PACKAGE_ROOT_PATH]
          [NO_CMAKE_PATH]
          [NO_CMAKE_ENVIRONMENT_PATH]
          [NO_SYSTEM_ENVIRONMENT_PATH]
          [NO_CMAKE_SYSTEM_PATH]
          [NO_CMAKE_INSTALL_PREFIX]
          [CMAKE_FIND_ROOT_PATH_BOTH |
           ONLY_CMAKE_FIND_ROOT_PATH |
           NO_CMAKE_FIND_ROOT_PATH]
         )

此命令用於尋找函式庫。會建立一個以 <VAR> 命名的快取條目，或如果指定 NO_CACHE 則為一般變數，以儲存此命令的結果。如果找到函式庫，結果會儲存在變數中，並且除非清除變數，否則不會重複搜尋。如果沒有找到任何東西，結果將會是 <VAR>-NOTFOUND。

選項包括

NAMES

指定一個或多個函式庫的可能名稱。

當使用此選項指定帶有和不帶有版本後綴的名稱時，我們建議先指定未帶版本的名稱，以便在發行版提供的套件之前找到本地構建的套件。

HINTS、PATHS

指定除了預設位置之外要搜尋的目錄。ENV var 子選項會從系統環境變數讀取路徑。

在 3.24 版本中變更: 在 Windows 平台上，可以使用 專用語法，將登錄查詢作為目錄的一部分包含在內。此類規格將在所有其他平台上被忽略。

REGISTRY_VIEW

在 3.24 版本中新增。

指定必須查詢哪個登錄檢視。此選項僅在 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

指定在其他考慮的每個目錄位置下方要檢查的其他子目錄。

VALIDATOR

在 3.25 版本中新增。

指定一個 function()，以便為找到的每個候選項目（無法提供 macro()，這會導致錯誤）呼叫。兩個引數會傳遞給驗證器函式：結果變數的名稱，以及候選項目的絕對路徑。除非函式將結果變數中的值設定為呼叫範圍中的 false，否則會接受該項目，並且搜尋將會結束。進入驗證器函式時，結果變數將會保持 true 值。

function(my_check validator_result_var item)
  if(NOT item MATCHES ...)
    set(${validator_result_var} FALSE PARENT_SCOPE)
  endif()
endfunction()

find_library (result NAMES ... VALIDATOR my_check)

請注意，如果使用快取的結果，則會略過搜尋，並且會忽略任何 VALIDATOR。快取的結果不需要通過驗證函式。

DOC

指定 <VAR> 快取條目的文件字串。

NO_CACHE

在 3.21 版本中新增。

搜尋結果會儲存在一般變數中，而不是快取條目中。

注意

如果變數在呼叫之前已經設定（作為一般或快取變數），則不會進行搜尋。

警告

應謹慎使用此選項，因為它會大幅增加重複組態步驟的成本。

REQUIRED

在 3.18 版本中新增。

如果找不到任何內容，則會停止處理並顯示錯誤訊息，否則下次以相同變數叫用 find_library 時，將會再次嘗試搜尋。

如果指定 NO_DEFAULT_PATH，則不會將其他路徑新增至搜尋。如果未指定 NO_DEFAULT_PATH，則搜尋流程如下

1. 如果從尋找模組或由呼叫 find_package(<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 版本中新增。

   套件根變數會維護為堆疊，因此如果從巢狀的尋找模組或組態套件呼叫，則會在目前模組或套件的路徑之後搜尋父級尋找模組或組態套件中的根路徑。換句話說，搜尋順序會是 <CurrentPackage>_ROOT、ENV{<CurrentPackage>_ROOT}、<ParentPackage>_ROOT、ENV{<ParentPackage>_ROOT} 等等。如果傳遞 NO_PACKAGE_ROOT_PATH 或將 CMAKE_FIND_USE_PACKAGE_ROOT_PATH 設定為 FALSE，則可以略過此步驟。

   • 如果設定了 CMAKE_LIBRARY_ARCHITECTURE，則為 <prefix>/lib/<arch>，對於 <PackageName>_ROOT CMake 變數和 <PackageName>_ROOT 環境變數中的每個 <prefix>，則為 <prefix>/lib，如果從由 find_package(<PackageName>) 載入的尋找模組內呼叫

2. 在 CMake 特定的快取變數中指定的搜尋路徑。這些變數旨在與 -DVAR=value 命令列選項一起使用。這些值會被解讀為以分號分隔的清單。如果傳遞 NO_CMAKE_PATH 或將 CMAKE_FIND_USE_CMAKE_PATH 設定為 FALSE，則可以跳過此步驟。

   • 如果設定了 CMAKE_LIBRARY_ARCHITECTURE，則為 <prefix>/lib/<arch>，對於 CMAKE_PREFIX_PATH 中的每個 <prefix> 則為 <prefix>/lib。

   • CMAKE_LIBRARY_PATH

   • CMAKE_FRAMEWORK_PATH

3. 在 CMake 特定的環境變數中指定的搜尋路徑。這些變數旨在設定在使用者 Shell 設定中，因此會使用主機的原生路徑分隔符號（Windows 上為 ;，UNIX 上為 :）。如果傳遞 NO_CMAKE_ENVIRONMENT_PATH 或將 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH 設定為 FALSE，則可以跳過此步驟。

   • 如果設定了 CMAKE_LIBRARY_ARCHITECTURE，則為 <prefix>/lib/<arch>，對於 CMAKE_PREFIX_PATH 中的每個 <prefix> 則為 <prefix>/lib。

   • CMAKE_LIBRARY_PATH

   • CMAKE_FRAMEWORK_PATH

4. 搜尋 HINTS 選項指定的路徑。這些路徑應該是由系統內省計算得出的路徑，例如已找到的另一個項目位置提供的提示。硬編碼的猜測應該使用 PATHS 選項來指定。

5. 搜尋標準的系統環境變數。如果傳遞 NO_SYSTEM_ENVIRONMENT_PATH 或將 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH 設定為 FALSE，則可以跳過此步驟。

   • LIB 和 PATH 中的目錄。

   在 Windows 主機上，CMake 3.3 到 3.27 會搜尋額外的路徑：如果設定了 CMAKE_LIBRARY_ARCHITECTURE，則為 <prefix>/lib/<arch>，對於 PATH 中的每個 <prefix>/[s]bin 則為 <prefix>/lib，對於 PATH 中的其他項目則為 <entry>/lib。CMake 3.28 移除了此行為。

6. 搜尋為當前系統在平台檔案中定義的 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，則可以跳過所有這些位置。

   • 如果設定了 CMAKE_LIBRARY_ARCHITECTURE，則為 <prefix>/lib/<arch>，對於 CMAKE_SYSTEM_PREFIX_PATH 中的每個 <prefix> 則為 <prefix>/lib。

   • CMAKE_SYSTEM_LIBRARY_PATH

   • CMAKE_SYSTEM_FRAMEWORK_PATH

   這些變數所包含的平台路徑通常包含已安裝的軟體。一個例子是基於 UNIX 的平台的 /usr/local。

7. 搜尋由 PATHS 選項或命令的簡寫版本指定的路徑。這些路徑通常是硬編碼的猜測。

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

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

在 macOS 上，CMAKE_FIND_FRAMEWORK 和 CMAKE_FIND_APPBUNDLE 變數決定 Apple 風格和 Unix 風格套件元件之間的偏好順序。

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_LIBRARY 來調整。這個行為也可以透過在每次呼叫時使用選項來手動覆寫。

CMAKE_FIND_ROOT_PATH_BOTH

依照上述順序進行搜尋。

NO_CMAKE_FIND_ROOT_PATH

不使用 CMAKE_FIND_ROOT_PATH 變數。

ONLY_CMAKE_FIND_ROOT_PATH

只搜尋重新設定根目錄的目錄和 CMAKE_STAGING_PREFIX 下的目錄。

預設的搜尋順序設計為從最特定到最不特定，以符合常見的使用情境。專案可以簡單地多次呼叫該指令並使用 NO_* 選項來覆寫順序。

find_library (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_library (<VAR> NAMES name)

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

當 NAMES 選項有多個值時，此指令預設會一次考慮一個名稱，並在每個目錄中進行搜尋。NAMES_PER_DIR 選項告訴此指令一次考慮一個目錄，並在其中搜尋所有名稱。

給定 NAMES 選項的每個程式庫名稱，會先被視為程式庫檔案名稱，然後再考慮平台特定的前綴（例如 lib）和後綴（例如 .so）。因此，可以直接指定程式庫檔案名稱，例如 libfoo.a。這可以用於在類 Unix 系統上定位靜態程式庫。

如果找到的程式庫是一個框架，則 <VAR> 將被設定為框架的完整路徑 <fullPath>/A.framework。當框架的完整路徑被用作程式庫時，CMake 將使用 -framework A 和 -F<fullPath> 來將框架連結到目標。

在 3.28 版本中新增: 現在找到的程式庫可以是 .xcframework 資料夾。

如果設定了 CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX 變數，所有搜尋路徑將會照常測試，並附加後綴，且所有 lib/ 的匹配項都會被替換為 lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX}/。此變數會覆寫 FIND_LIBRARY_USE_LIB32_PATHS、FIND_LIBRARY_USE_LIBX32_PATHS 和 FIND_LIBRARY_USE_LIB64_PATHS 全域屬性。

如果設定了 FIND_LIBRARY_USE_LIB32_PATHS 全域屬性，所有搜尋路徑將會照常測試，並附加 32/，且所有 lib/ 的匹配項都會被替換為 lib32/。如果 project() 指令支援的至少一種語言啟用時，此屬性會自動針對已知需要它的平台設定。

如果設定了 FIND_LIBRARY_USE_LIBX32_PATHS 全域屬性，所有搜尋路徑將會照常測試，並附加 x32/，且所有 lib/ 的匹配項都會被替換為 libx32/。如果 project() 指令支援的至少一種語言啟用時，此屬性會自動針對已知需要它的平台設定。

如果設定了 FIND_LIBRARY_USE_LIB64_PATHS 全域屬性，所有搜尋路徑將會照常測試，並附加 64/，且所有 lib/ 的匹配項都會被替換為 lib64/。如果 project() 指令支援的至少一種語言啟用時，此屬性會自動針對已知需要它的平台設定。