FindMPI

尋找訊息傳遞介面 (MPI) 實作。

訊息傳遞介面 (MPI) 是一個用於編寫高效能分散式記憶體平行應用程式的函式庫，通常部署在叢集上。MPI 是一個標準介面（由 MPI 論壇定義），有多種實作可用。

在版本 3.10 中新增：模組的大幅改進：許多新變數、每個語言的元件，支援更廣泛的執行時環境。

使用 MPI 的變數

此模組公開了 C、 CXX、 MPICXX 和 Fortran 元件。 每個元件都控制要搜尋的各種 MPI 語言。CXX 和 MPICXX 之間的區別在於，CXX 指的是可從 C++ 使用的 MPI C API，而 MPICXX 指的是 MPI-2 C++ API，該 API 在 MPI-3 中再次移除。

根據啟用的元件，將設定以下變數

MPI_FOUND

指示已找到所有請求語言的 MPI 設定的變數。 如果未指定任何元件，則如果偵測到所有已啟用語言的 MPI 設定，則此變數為 true。 請注意，MPICXX 元件不會影響此變數。

MPI_VERSION

在請求的語言中偵測到的最小 MPI 版本，如果未指定任何元件，則為所有已啟用語言中偵測到的最小版本。

此模組將在您的專案中為每個語言設定以下變數，其中 <lang> 是 C、CXX 或 Fortran 其中之一

MPI_<lang>_FOUND

指示已找到 <lang> 的 MPI 設定，並且簡單的 MPI 測試程式可以使用提供的設定進行編譯的變數。

MPI_<lang>_COMPILER

如果存在此程式，則為 <lang> 的 MPI 編譯器。

MPI_<lang>_COMPILE_OPTIONS

以 ;-list 形式給出的 <lang> 中 MPI 程式的編譯選項。

MPI_<lang>_COMPILE_DEFINITIONS

以 ;-list 形式給出的 <lang> 中 MPI 程式的編譯定義。

MPI_<lang>_INCLUDE_DIRS

MPI 標頭的包含路徑。

MPI_<lang>_LINK_FLAGS

MPI 程式的連結器旗標。

MPI_<lang>_LIBRARIES

所有要連結 MPI 程式的函式庫。

在版本 3.9 中新增：此外，定義了以下 IMPORTED 目標

MPI::MPI_<lang>

從 <lang> 使用 MPI 的目標。

將定義以下指示存在哪些繫結的變數

MPI_MPICXX_FOUND

指示是否存在 MPI-2 C++ 繫結的變數（在 MPI-2 中引入，在 MPI-3 中移除）。

MPI_Fortran_HAVE_F77_HEADER

如果 Fortran 77 標頭 mpif.h 可用，則為 True。

MPI_Fortran_HAVE_F90_MODULE

如果 Fortran 90 模組 mpi 可以用於存取 MPI（僅限 MPI-2 及更高版本），則為 True。

MPI_Fortran_HAVE_F08_MODULE

如果 Fortran 2008 mpi_f08 可用於 MPI 程式（僅限 MPI-3 及更高版本），則為 True。

如果可能，此模組將會判斷 MPI 版本。 偵測 MPI 版本的功能是在 MPI-1.2 中引入的，因此對於較舊的 MPI 版本無法找到。

MPI_<lang>_VERSION_MAJOR

MPI 發行版本針對 <lang> 實作的 MPI 主要版本。

MPI_<lang>_VERSION_MINOR

MPI 發行版本針對 <lang> 實作的 MPI 次要版本。

MPI_<lang>_VERSION

MPI 發行版本針對 <lang> 實作的 MPI 版本。

請注意，沒有變數表示可透過 mpi.h 存取 C 繫結，因為 MPI 標準始終要求此繫結在 C 和 C++ 程式碼中都可正常運作。

為了執行 MPI 程式，此模組設定了以下變數

MPIEXEC_EXECUTABLE

如果存在，則為執行 MPI 程式的可執行檔。

MPIEXEC_NUMPROC_FLAG

在給定要執行的處理器數量之前傳遞給 mpiexec 的旗標。

MPIEXEC_MAX_NUMPROCS

要使用的 MPI 處理器數量。 預設為在主機系統上偵測到的處理器數量。

MPIEXEC_PREFLAGS

直接在要執行的可執行檔之前傳遞給 mpiexec 的旗標。

MPIEXEC_POSTFLAGS

在其他旗標之後傳遞給 mpiexec 的旗標。

用於尋找 MPI 的變數

此模組對 MPI 實作執行四個步驟的搜尋

  1. 搜尋 MPIEXEC_EXECUTABLE，如果找到，則使用其基本目錄。

  2. 檢查編譯器是否內建 MPI 支援。 如果使用者傳遞編譯器包裝器作為 CMAKE_<LANG>_COMPILER，或者如果他們使用 Cray 系統編譯器包裝器，則會發生這種情況。

  3. 嘗試尋找 MPI 編譯器包裝器並從中判斷編譯器資訊。

  4. 嘗試透過猜測設定來尋找未隨附此包裝器的 MPI 實作。 目前，僅支援 Windows 上的 Microsoft MPI 和 MPICH2。

為了控制 MPIEXEC_EXECUTABLE 步驟，可以設定以下變數

MPIEXEC_EXECUTABLE

手動指定 mpiexec 的位置。

MPI_HOME

指定 MPI 安裝的基本目錄。

ENV{MPI_HOME}

用於指定 MPI 安裝基本目錄的環境變數。

ENV{I_MPI_ROOT}

用於指定 MPI 安裝基本目錄的環境變數。

為了控制編譯器包裝器步驟，可以設定以下變數

MPI_<lang>_COMPILER

搜尋指定的編譯器包裝器並使用它。

MPI_<lang>_COMPILER_FLAGS

在盤問期間傳遞給 MPI 編譯器包裝器的旗標。 如果傳遞特定旗標，某些編譯器包裝器支援連結偵錯或追蹤函式庫，此變數可用於取得它們。

MPI_COMPILER_FLAGS

如果未提供語言特定旗標，則用於初始化 MPI_<lang>_COMPILER_FLAGS。 預設為空。

MPI_EXECUTABLE_SUFFIX

附加到所有要搜尋的名稱的後綴。 例如，您可以將此設定為 .mpich 或 .openmpi，以便在 Debian 及其衍生版本上優先選擇其中一個。

為了控制猜測步驟，可以設定以下變數

MPI_GUESS_LIBRARY_NAME

有效值為 MSMPI 和 MPICH2。 如果設定，則只會搜尋指定的函式庫。 預設情況下，如果兩者都可用，則 MSMPI 的優先順序高於 MPICH2。 這也會將 MPI_SKIP_COMPILER_WRAPPER 設定為 true，這可以被覆寫。

可以使用以下控制變數略過每個搜尋步驟

MPI_ASSUME_NO_BUILTIN_MPI

如果為 true，則模組會假設編譯器本身未提供 MPI 實作，並跳至步驟 2。

MPI_SKIP_COMPILER_WRAPPER

如果為 true，則不會搜尋任何編譯器包裝器。

MPI_SKIP_GUESSING

如果為 true，則會略過猜測步驟。

此外，可以使用以下控制變數來變更搜尋行為

MPI_CXX_SKIP_MPICXX

新增一些將停用 MPI-2 C++ 繫結的定義。 目前支援 MPICH、Open MPI、Platform MPI 及其衍生版本，例如 MVAPICH 或 Intel MPI。

如果變數 MPI_<lang>_WORKS 的尋找程序失敗，則表示模組偵測到或傳遞給模組的設定不起作用，甚至簡單的 MPI 測試程式也無法編譯。

如果所有這些參數都不足以找到正確的 MPI 實作，則使用者可以透過在 MPI_<lang>_LIBRARIES 中指定函式庫清單，以及在 MPI_<lang>_ADDITIONAL_INCLUDE_DIRS 中指定包含目錄清單來停用整個自動偵測程序。 除了這兩個變數之外，還可以設定任何其他變數。 然後，模組將驗證 MPI 設定並將設定儲存在快取中。

用於 MPI 的快取變數

變數 MPI_<lang>_INCLUDE_DIRS 將由以下變數組裝而成。 適用於 C 和 CXX

MPI_<lang>_HEADER_DIR

磁碟上 mpi.h 標頭的位置。

適用於 Fortran

MPI_Fortran_F77_HEADER_DIR

Fortran 77 標頭 mpif.h 的位置（如果存在）。

MPI_Fortran_MODULE_DIR

模組 mpi 或 mpi_f08 的位置（如果可用）。

對於所有語言，還會額外考量以下變數：

MPI_<lang>_ADDITIONAL_INCLUDE_DIRS

一個以分號分隔的列表，其中包含除了正常 include 目錄之外還需要的路徑。

MPI_<include_name>_INCLUDE_DIR

由 <include_name> 參照的 include 資料夾的路徑變數。

MPI_<lang>_ADDITIONAL_INCLUDE_VARS

一個以分號分隔的列表，其中包含將會加入 <lang> 的 include 位置的 <include_name>。

變數 MPI_<lang>_LIBRARIES 將由以下變數組成：

MPI_<lib_name>_LIBRARY

一個名為 <lib_name> 的函式庫的位置，用於 MPI。

MPI_<lang>_LIB_NAMES

一個以分號分隔的列表，其中包含將會加入 <lang> 的 include 位置的 <lib_name>。

mpiexec 的用法

當使用 MPIEXEC_EXECUTABLE 執行 MPI 應用程式時，您通常應該使用所有 MPIEXEC_EXECUTABLE 的旗標，如下所示：

${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${MPIEXEC_MAX_NUMPROCS}
  ${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS

其中 EXECUTABLE 是 MPI 程式，而 ARGS 是要傳遞給 MPI 程式的引數。

使用 MPI 的進階變數

此模組可以根據明確請求執行一些進階的功能偵測。

重要注意事項： 如果不執行 MPI 測試程式，則無法執行以下檢查。請考量在交叉編譯期間 try_run() 行為的特殊考量。此外，執行 MPI 程式可能會導致其他問題，例如在某些系統上出現防火牆通知。您應該僅在絕對需要資訊時啟用這些偵測。

如果以下變數設定為 true，則將執行相應的搜尋：

MPI_DETERMINE_Fortran_CAPABILITIES

為所有可用的 Fortran 綁定判斷 MPI_SUBARRAYS_SUPPORTED 和 MPI_ASYNC_PROTECTS_NONBLOCKING 的值，並使其值可作為 MPI_Fortran_<binding>_SUBARRAYS 和 MPI_Fortran_<binding>_ASYNCPROT 使用，其中 <binding> 是 F77_HEADER、F90_MODULE 和 F08_MODULE 其中之一。

MPI_DETERMINE_LIBRARY_VERSION

對於每種語言，尋找 MPI_Get_library_version 的輸出，並使其可作為 MPI_<lang>_LIBRARY_VERSION_STRING 使用。此資訊通常與 MPI 實作的執行時期元件相關聯，並且可能會因 <lang> 而異。請注意，傳回值完全由實作定義。此資訊可用於識別 MPI 供應商，例如從多個符合 MPI 供應商的第三方二進位檔中選擇正確的一個。

回溯相容性

自 3.10 版起已棄用。

為了與舊版本的 FindMPI 回溯相容，會設定以下變數：

MPI_COMPILER        MPI_LIBRARY        MPI_EXTRA_LIBRARY
MPI_COMPILE_FLAGS   MPI_INCLUDE_PATH   MPI_LINK_FLAGS
MPI_LIBRARIES

在新的專案中，請使用 MPI_<lang>_XXX 對等項目。此外，以下變數已棄用：

MPI_<lang>_COMPILE_FLAGS

請改用 MPI_<lang>_COMPILE_OPTIONS 和 MPI_<lang>_COMPILE_DEFINITIONS。

MPI_<lang>_INCLUDE_PATH

若要使用，請使用 MPI_<lang>_INCLUDE_DIRS，若要指定資料夾，請改用 MPI_<lang>_ADDITIONAL_INCLUDE_DIRS。

MPIEXEC

請改用 MPIEXEC_EXECUTABLE。