# FindMPI

Find a Message Passing Interface (MPI) implementation

The Message Passing Interface (MPI) is a library used to write high-performance distributed-memory parallel applications, and is typically deployed on a cluster. MPI is a standard interface (defined by the MPI forum) for which many implementations are available.

## Variables

This module will set the following variables per language in your project, where `<lang>` is one of C, CXX, or Fortran:

`MPI_<lang>_FOUND`
  Variable indicating the MPI settings for `<lang>` were found.
`MPI_<lang>_COMPILER`
  MPI Compiler wrapper for `<lang>`.
`MPI_<lang>_COMPILE_FLAGS`
  Compilation flags for MPI programs, separated by spaces. This is not a ;-list.
`MPI_<lang>_INCLUDE_PATH`
  Include path(s) for MPI header.
`MPI_<lang>_LINK_FLAGS`
  Linker flags for MPI programs.
`MPI_<lang>_LIBRARIES`
  All libraries to link MPI programs against.

Additionally, the following `IMPORTED` targets are defined:

`MPI::MPI_<lang>`
  Target for using MPI from `<lang>`.

Additionally, FindMPI sets the following variables for running MPI programs from the command line:

`MPIEXEC`
  Executable for running MPI programs, if provided.
`MPIEXEC_NUMPROC_FLAG`
  Flag to pass to `MPIEXEC` before giving it the number of processors to run on.
`MPIEXEC_MAX_NUMPROCS`
  Number of MPI processors to utilize. Defaults to the number of processors detected on the host system.
`MPIEXEC_PREFLAGS`
  Flags to pass to `MPIEXEC` directly before the executable to run.
`MPIEXEC_POSTFLAGS`
  Flags to pass to `MPIEXEC` after other flags.

## Usage

To use this module, call `find_package(MPI)`. If you are happy with the auto-detected configuration for your language, then you’re done. If not, you have two options:

1. Set `MPI_<lang>_COMPILER` to the MPI wrapper (e.g. `mpicc`) of your choice and reconfigure. FindMPI will attempt to determine all the necessary variables using that compiler’s compile and link flags.
2. If this fails, or if your MPI implementation does not come with a compiler wrapper, then set both `MPI_<lang>_LIBRARIES` and `MPI_<lang>_INCLUDE_PATH`. You may also set any other variables listed above, but these two are required. This will circumvent autodetection entirely.

When configuration is successful, `MPI_<lang>_COMPILER` will be set to the compiler wrapper for `<lang>`, if it was found. `MPI_<lang>_FOUND` and other variables above will be set if any MPI implementation was found for `<lang>`, regardless of whether a compiler was found.

When using `MPIEXEC` to execute MPI applications, you should typically use all of the `MPIEXEC` flags as follows:

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

where `EXECUTABLE` is the MPI program, and `ARGS` are the arguments to pass to the MPI program.

## Backward Compatibility

For backward compatibility with older versions of FindMPI, these variables are set, but deprecated:

    MPI_FOUND           MPI_COMPILER        MPI_LIBRARY
    MPI_COMPILE_FLAGS   MPI_INCLUDE_PATH    MPI_EXTRA_LIBRARY
    MPI_LINK_FLAGS      MPI_LIBRARIES

In new projects, please use the `MPI_<lang>_XXX` equivalents.