find_program¶

簡短的簽名是

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

一般的簽名是

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

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

選項包含

NAMES

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

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

HINTS、PATHS

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

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

REGISTRY_VIEW

在 3.24 版本中新增。

指定必須查詢的登錄檢視。此選項僅在 Windows 平台上才有意義，在其他平台上將被忽略。如果未指定，當 CMP0134 策略為 NEW 時，會使用 BOTH 檢視。當策略為 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_program (result NAMES ... VALIDATOR my_check)

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

DOC

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

NO_CACHE

在 3.21 版本中新增。

搜尋結果將儲存在普通變數中，而不是快取條目中。

注意

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

警告

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

REQUIRED

在 3.18 版本中新增。

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

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

如果從 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，則可以跳過此步驟。
- 對於透過 find_package(<PackageName>) 載入的 find 模組中呼叫的每個 <prefix>，<prefix>/[s]bin 在 <PackageName>_ROOT CMake 變數和 <PackageName>_ROOT 環境變數中。
在 CMake 特定的快取變數中指定的搜尋路徑。這些變數旨在透過命令列使用，並搭配 -DVAR=value。這些值會被解讀為以分號分隔的列表。如果傳遞了 NO_CMAKE_PATH，或是將 CMAKE_FIND_USE_CMAKE_PATH 設定為 FALSE，則可以跳過此步驟。
- 對於 CMAKE_PREFIX_PATH 中的每個 <prefix>，會搜尋 <prefix>/[s]bin。
- CMAKE_PROGRAM_PATH
- CMAKE_APPBUNDLE_PATH
在 CMake 特定的環境變數中指定的搜尋路徑。這些變數旨在於使用者的 Shell 設定中設定，因此使用主機的原生路徑分隔符號（在 Windows 上為 ;，在 UNIX 上為 :）。如果傳遞了 NO_CMAKE_ENVIRONMENT_PATH，或是將 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH 設定為 FALSE，則可以跳過此步驟。
- 對於 CMAKE_PREFIX_PATH 中的每個 <prefix>，會搜尋 <prefix>/[s]bin。
- CMAKE_PROGRAM_PATH
- CMAKE_APPBUNDLE_PATH
搜尋由 HINTS 選項指定的路徑。這些應該是由系統內省計算的路徑，例如已經找到的另一個項目位置所提供的提示。硬編碼的猜測應該使用 PATHS 選項指定。
搜尋標準系統環境變數。如果傳遞了 NO_SYSTEM_ENVIRONMENT_PATH，或是將 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH 設定為 FALSE，則可以跳過此步驟。
- 搜尋 PATH 本身中的目錄。
搜尋在目前系統的平台檔案中定義的 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_SYSTEM_PREFIX_PATH 中的每個 <prefix>，會搜尋 <prefix>/[s]bin。
- CMAKE_SYSTEM_PROGRAM_PATH
- CMAKE_SYSTEM_APPBUNDLE_PATH
這些變數包含的平台路徑是通常包含已安裝軟體的位置。例如，UNIX 平台上的 /usr/local。
搜尋由 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_PROGRAM 來調整預設行為。可以使用選項在每次呼叫的基礎上手動覆寫此行為。

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

預設的搜尋順序設計為對於常見用例而言，從最特定到最不特定。專案可以透過多次呼叫命令並使用 NO_* 選項來覆寫順序。

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

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

當 NAMES 選項被賦予多個值時，此命令預設會一次考慮一個名稱，並在每個目錄中搜尋。 NAMES_PER_DIR 選項則指示此命令一次考慮一個目錄，並在該目錄中搜尋所有名稱。

被視為程式的檔案集合會因平台而異。

在 Windows 上，會依序考慮檔案名稱後綴 .com、 .exe 和無後綴。
在非 Windows 系統上，不會考慮任何檔案名稱後綴，但檔案必須具有執行權限（請參閱政策 CMP0109）。

若要搜尋腳本，請明確指定副檔名。

if(WIN32)
  set(_script_suffix .bat)
else()
  set(_script_suffix .sh)
endif()

find_program(MY_SCRIPT NAMES my_script${_script_suffix})

find_program¶

上一主題

下一主題

本頁