From ece4f647491eb81d3be55881a47752ce4ff88da9 Mon Sep 17 00:00:00 2001 From: Christian Pfeiffer Date: Fri, 21 Apr 2017 20:02:20 +0200 Subject: FindMPI: Modernize documentation --- Modules/FindMPI.cmake | 89 ++++++++++++++++++++++++++------------------------- 1 file changed, 45 insertions(+), 44 deletions(-) diff --git a/Modules/FindMPI.cmake b/Modules/FindMPI.cmake index 5f64855..fab53cb 100644 --- a/Modules/FindMPI.cmake +++ b/Modules/FindMPI.cmake @@ -10,77 +10,78 @@ # 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. All -# of them have somewhat different include paths, libraries to link -# against, etc., and this module tries to smooth out those differences. +# by the MPI forum) for which many implementations are available. # # Variables # ^^^^^^^^^ # # This module will set the following variables per language in your -# project, where is one of C, CXX, or Fortran: -# -# :: -# -# MPI__FOUND TRUE if FindMPI found MPI flags for -# MPI__COMPILER MPI Compiler wrapper for -# MPI__COMPILE_FLAGS Compilation flags for MPI programs -# MPI__INCLUDE_PATH Include path(s) for MPI header -# MPI__LINK_FLAGS Linking flags for MPI programs -# MPI__LIBRARIES All libraries to link MPI programs against +# project, where ```` is one of C, CXX, or Fortran: +# +# ``MPI__FOUND`` +# Variable indicating the MPI settings for ```` were found. +# ``MPI__COMPILER`` +# MPI Compiler wrapper for ````. +# ``MPI__COMPILE_FLAGS`` +# Compilation flags for MPI programs, separated by spaces. +# This is *not* a :ref:`;-list `. +# ``MPI__INCLUDE_PATH`` +# Include path(s) for MPI header. +# ``MPI__LINK_FLAGS`` +# Linker flags for MPI programs. +# ``MPI__LIBRARIES`` +# All libraries to link MPI programs against. # # Additionally, the following :prop_tgt:`IMPORTED` targets are defined: # -# :: -# -# MPI::MPI_ Target for using MPI from +# ``MPI::MPI_`` +# Target for using MPI from ````. # # Additionally, FindMPI sets the following variables for running MPI # programs from the command line: # -# :: -# -# MPIEXEC Executable for running MPI programs -# MPIEXEC_NUMPROC_FLAG Flag to pass to MPIEXEC before giving -# it the number of processors to run on -# MPIEXEC_PREFLAGS Flags to pass to MPIEXEC directly -# before the executable to run. -# MPIEXEC_POSTFLAGS Flags to pass to MPIEXEC after other flags +# ``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, simply call FindMPI from a CMakeLists.txt file, or -# run ``find_package(MPI)``, then run CMake. If you are happy with the +# 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__COMPILER to the MPI wrapper (mpicc, etc.) 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__LIBRARIES and -# MPI__INCLUDE_PATH. You may also set any other variables -# listed above, but these two are required. This will circumvent -# autodetection entirely. +# 1. Set ``MPI__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__LIBRARIES`` and +# ``MPI__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__COMPILER`` will be set to -# the compiler wrapper for , if it was found. ``MPI__FOUND`` +# the compiler wrapper for ````, if it was found. ``MPI__FOUND`` # and other variables above will be set if any MPI implementation was -# found for , regardless of whether a compiler was found. +# found for ````, 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} PROCS +# ${MPIEXEC} ${MPIEXEC_NUMPROC_FLAG} ${MPIEXEC_MAX_NUMPROCS} # ${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS # -# where ``PROCS`` is the number of processors on which to execute the -# program, ``EXECUTABLE`` is the MPI program, and ``ARGS`` are the arguments to +# where ``EXECUTABLE`` is the MPI program, and ``ARGS`` are the arguments to # pass to the MPI program. # # Backward Compatibility @@ -106,12 +107,12 @@ include(${CMAKE_CURRENT_LIST_DIR}/FindPackageHandleStandardArgs.cmake) # The compilers are detected in this order: # # 1. Try to find the most generic available MPI compiler, as this is usually set up by -# cluster admins. e.g., if plain old mpicc is available, we'll use it and assume it's +# cluster admins, e.g. if plain old mpicc is available, we'll use it and assume it's # the right compiler. # # 2. If a generic mpicc is NOT found, then we attempt to find one that matches # CMAKE__COMPILER_ID. e.g. if you are using XL compilers, we'll try to find mpixlc -# and company, but not mpiicc. This hopefully prevents toolchain mismatches. +# and company, but not mpiicc. This hopefully prevents toolchain mismatches. # # If you want to force a particular MPI compiler other than what we autodetect (e.g. if you # want to compile regular stuff with GNU and parallel stuff with Intel), you can always set @@ -482,7 +483,7 @@ function (interrogate_mpi_compiler lang try_libs) set(MPI_${lang}_LIBRARIES ${MPI_LIBRARIES_WORK} CACHE STRING "MPI ${lang} libraries to link against" FORCE) mark_as_advanced(MPI_${lang}_COMPILE_FLAGS MPI_${lang}_INCLUDE_PATH MPI_${lang}_LINK_FLAGS MPI_${lang}_LIBRARIES) - # clear out our temporary lib/header detectionv variable here. + # clear out our temporary lib/header detection variable here. set(MPI_LIB "MPI_LIB-NOTFOUND" CACHE INTERNAL "Scratch variable for MPI lib detection" FORCE) set(MPI_HEADER_PATH "MPI_HEADER_PATH-NOTFOUND" CACHE INTERNAL "Scratch variable for MPI header detection" FORCE) endif() -- cgit v0.12