find_path

簡短簽名為

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

一般簽名為

find_path (
          <VAR>
          name | NAMES name1 [name2 ...]
          [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]
         )

此命令用於尋找包含指定檔案的目錄。將建立一個快取項目，或在指定 NO_CACHE 時建立一般變數，並以 <VAR> 命名，以儲存此命令的結果。如果在目錄中找到檔案，結果將儲存在變數中，除非變數被清除，否則不會重複搜尋。如果找不到任何內容，結果將為 <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_path (result NAMES ... VALIDATOR my_check)

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

DOC

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

NO_CACHE

在 3.21 版本中新增。

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

注意

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

警告

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

REQUIRED

在 3.18 版本中新增。

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

如果指定了 NO_DEFAULT_PATH，則不會將其他路徑新增到搜尋中。如果未指定 NO_DEFAULT_PATH，則搜尋過程如下

  1. 如果從 find 模組或透過調用 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 版本中新增。

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

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

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

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

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

    • INCLUDE 和 PATH 中的目錄。

    在 Windows 主機上，CMake 3.3 到 3.27 搜尋了其他路徑：如果設定了 CMAKE_LIBRARY_ARCHITECTURE，則為 <prefix>/include/<arch>，以及 <prefix>/include，適用於 PATH 中的每個 <prefix>/[s]bin，以及 <entry>/include，適用於 PATH 中的其他項目。此行為已在 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，則可以跳過所有這些位置。

    這些變數包含的平台路徑是通常包含已安裝軟體的位置。例如，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_INCLUDE 進行調整。可以使用選項在每次調用的基礎上手動覆寫此行為

CMAKE_FIND_ROOT_PATH_BOTH

以上述順序搜尋。

NO_CMAKE_FIND_ROOT_PATH

不使用 CMAKE_FIND_ROOT_PATH 變數。

ONLY_CMAKE_FIND_ROOT_PATH

僅搜尋重新紮根的目錄和 CMAKE_STAGING_PREFIX 下方的目錄。

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

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

一旦其中一個調用成功，結果變數將被設定並儲存在快取中，以便沒有調用會再次搜尋。

搜尋框架時，如果檔案指定為 A/b.h，則框架搜尋將尋找 A.framework/Headers/b.h。如果找到，路徑將設定為框架的路徑。CMake 會將其轉換為正確的 -F 選項以包含檔案。