ENH: Enhance FindMPI module by properly handling backward compatibility with the older module, adding documentation, and coping with multiple include and linker paths

1 files changed, 132 insertions, 96 deletions

diff --git a/Modules/FindMPI.cmake b/Modules/FindMPI.cmake
index 627effc..5e218e7 100644
--- a/Modules/FindMPI.cmake
+++ b/Modules/FindMPI.cmake
@@ -1,95 +1,132 @@
-# This module looks for the Message Passing Interface (MPI).
+# - Message Passing Interface (MPI) module.
+# 
+# The Message Passing Interface (MPI) is a library used to write
+# high-performance parallel applications that use message passing, 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 these implementations have somewhat different
+# compilation approaches (different include paths, libraries to link
+# against, etc.), and this module tries to smooth out those differences.
 #
 # This module will set the following variables:
 #   MPI_FOUND                  TRUE if we have found MPI
 #   MPI_COMPILE_FLAGS          Compilation flags for MPI programs
-#   MPI_INCLUDE_PATH           Include path for MPI header
+#   MPI_INCLUDE_PATH           Include path(s) for MPI header
 #   MPI_LINK_FLAGS             Linking flags for MPI programs
-#   MPI_LIBRARIES              Libraries to link MPI programs against
-#   MPI_LIBRARY                Deprecated; first MPI library to link against
-#   MPI_EXTRA_LIBRARY          Deprecated; second MPI library to link against
+#   MPI_LIBRARY                First MPI library to link against (cached)
+#   MPI_EXTRA_LIBRARY          Extra MPI libraries to link against (cached)
+#   MPI_LIBRARIES              All libraries to link MPI programs against
 #   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 all other flags.
 #
 # This module will attempt to auto-detect these settings, first by
-# looking for a C++ MPI driver (e.g., mpic++, mpiCC, or mpicxx; set by
-# MPICXX) and later by checking common MPI paths and library names.
+# looking for a MPI compiler, which many MPI implementations provide
+# as a pass-through to the native compiler to simplify the compilation
+# of MPI programs. The MPI compiler is stored in the cache variable
+# MPI_COMPILER, and will attempt to look for commonly-named drivers
+# mpic++, mpicxx, mpiCC, or mpicc. If the compiler driver is found and
+# recognized, it will be used to set all of the module variables. To
+# skip this auto-detection, set MPI_LIBRARY and MPI_INCLUDE_PATH in
+# the CMake cache.
+#
+# If no compiler driver is found or the compiler driver is not
+# recognized, this module will then search for common include paths
+# and library names to try to detect MPI. 
+#
+# If CMake initially finds a different MPI than was intended, and you
+# want to use the MPI compiler auto-detection for a different MPI
+# implementation, set MPI_COMPILER to the MPI compiler driver you want
+# to use (e.g., mpicxx) and then set MPI_LIBRARY to the string
+# MPI_LIBRARY-NOTFOUND. When you re-configure, auto-detection of MPI
+# will run again with the newly-specified MPI_COMPILER.
+#
+# When using MPIEXEC to execute MPI applications, you should typically
+# use all of the MPIEXEC flags as follows:
+#   ${MPIEXEC} ${MPIEXEC_NUMPROC_FLAG} PROCS ${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 pass to the 
+# MPI program.
 
 # Try to find the MPI driver program
-find_program(MPICXX 
-  NAMES mpic++ mpicxx mpiCC
-  DOC "MPI C++ compiler. Used only to detect MPI compilation flags.")
-mark_as_advanced(MPICXX)
+find_program(MPI_COMPILER 
+  NAMES mpic++ mpicxx mpiCC mpicc
+  DOC "MPI compiler. Used only to detect MPI compilation flags.")
+mark_as_advanced(MPI_COMPILER)
 
 find_program(MPIEXEC
-  NAMES mpiexec mpirun
+  NAMES mpiexec mpirun lamexec
   DOC "Executable for running MPI programs.")
-mark_as_advanced(MPIEXEC)
 
-if (NOT OLD_MPICXX STREQUAL MPICXX)
-  set(MPI_FORCE_RECONFIGURE TRUE)
-  set(OLD_MPICXX ${MPICXX} CACHE INTERNAL "Previous value of MPICXX" FORCE)
-endif (NOT OLD_MPICXX STREQUAL MPICXX)
-  
-if (NOT MPICXX)
-  # If there is no MPI C++ compiler, we force ourselves to configure
-  # MPI the old way.
-  set(MPI_FORCE_RECONFIGURE TRUE)
-endif (NOT MPICXX)
+set(MPIEXEC_NUMPROC_FLAG "-np" CACHE STRING "Flag used by MPI to specify the number of processes for MPIEXEC; the next option will be the number of processes.")
+set(MPIEXEC_PREFLAGS "" CACHE STRING "These flags will be directly before the executable that is being run by MPIEXEC.")
+set(MPIEXEC_POSTFLAGS "" CACHE STRING "These flags will come after all flags given to MPIEXEC.")
+set(MPIEXEC_MAX_NUMPROCS "2" CACHE STRING "Maximum number of processors available to run MPI applications.")
+mark_as_advanced(MPIEXEC MPIEXEC_NUMPROC_FLAG MPIEXEC_PREFLAGS 
+  MPIEXEC_POSTFLAGS MPIEXEC_MAX_NUMPROCS)
 
-if (MPICXX)
+if (MPI_INCLUDE_PATH AND MPI_LIBRARY)
+  # Do nothing: we already have MPI_INCLUDE_PATH and MPI_LIBRARY in
+  # the cache, and we don't want to override those settings.
+elseif (MPI_COMPILER)
   # Check whether the -showme:compile option works. This indicates
   # that we have either Open MPI or a newer version of LAM-MPI, and
   # implies that -showme:link will also work.
-  exec_program(${MPICXX} 
+  exec_program(${MPI_COMPILER} 
     ARGS -showme:compile 
     OUTPUT_VARIABLE MPI_COMPILE_CMDLINE
-    RETURN_VALUE MPICXX_RETURN)
+    RETURN_VALUE MPI_COMPILER_RETURN)
 
-  if (MPICXX_RETURN EQUAL 0)
+  if (MPI_COMPILER_RETURN EQUAL 0)
     # If we appear to have -showme:compile, then we should also have
     # -showme:link. Try it.
-    exec_program(${MPICXX} 
+    exec_program(${MPI_COMPILER} 
       ARGS -showme:link
       OUTPUT_VARIABLE MPI_LINK_CMDLINE
-      RETURN_VALUE MPICXX_RETURN)
-  endif (MPICXX_RETURN EQUAL 0)
+      RETURN_VALUE MPI_COMPILER_RETURN)
+  endif (MPI_COMPILER_RETURN EQUAL 0)
 
-  if (MPICXX_RETURN EQUAL 0)
+  if (MPI_COMPILER_RETURN EQUAL 0)
     # Do nothing: we have our command lines now
-  else (MPICXX_RETURN EQUAL 0)
+  else (MPI_COMPILER_RETURN EQUAL 0)
     # Older versions of LAM-MPI have "-showme". Try it.
-    exec_program(${MPICXX} 
+    exec_program(${MPI_COMPILER} 
       ARGS -showme
       OUTPUT_VARIABLE MPI_COMPILE_CMDLINE
-      RETURN_VALUE MPICXX_RETURN)
-  endif (MPICXX_RETURN EQUAL 0)  
+      RETURN_VALUE MPI_COMPILER_RETURN)
+  endif (MPI_COMPILER_RETURN EQUAL 0)  
 
-  if (MPICXX_RETURN EQUAL 0)
+  if (MPI_COMPILER_RETURN EQUAL 0)
     # Do nothing: we have our command lines now
-  else (MPICXX_RETURN EQUAL 0)
+  else (MPI_COMPILER_RETURN EQUAL 0)
     # MPICH uses "-show". Try it.
-    exec_program(${MPICXX} 
+    exec_program(${MPI_COMPILER} 
       ARGS -show
       OUTPUT_VARIABLE MPI_COMPILE_CMDLINE
-      RETURN_VALUE MPICXX_RETURN)
-  endif (MPICXX_RETURN EQUAL 0)  
+      RETURN_VALUE MPI_COMPILER_RETURN)
+  endif (MPI_COMPILER_RETURN EQUAL 0)  
 
-  if (MPICXX_RETURN EQUAL 0)
+  if (MPI_COMPILER_RETURN EQUAL 0)
     # We have our command lines, but we might need to copy
     # MPI_COMPILE_CMDLINE into MPI_LINK_CMDLINE, if the underlying
     if (NOT MPI_LINK_CMDLINE)
       SET(MPI_LINK_CMDLINE ${MPI_COMPILE_CMDLINE})
     endif (NOT MPI_LINK_CMDLINE)
-  else (MPICXX_RETURN EQUAL 0)
-    message(STATUS "Unable to determine MPI from MPI driver ${MPICXX}")
-  endif (MPICXX_RETURN EQUAL 0)
-endif (MPICXX)
+  else (MPI_COMPILER_RETURN EQUAL 0)
+    message(STATUS "Unable to determine MPI from MPI driver ${MPI_COMPILER}")
+  endif (MPI_COMPILER_RETURN EQUAL 0)
+endif (MPI_INCLUDE_PATH AND MPI_LIBRARY)
 
-if (NOT MPI_FORCE_RECONFIGURE)
-  # We don't actually have to reconfigure anything
+if (MPI_INCLUDE_PATH AND MPI_LIBRARY)
+  # Do nothing: we already have MPI_INCLUDE_PATH and MPI_LIBRARY in
+  # the cache, and we don't want to override those settings.
 elseif (MPI_COMPILE_CMDLINE)
   # Extract compile flags from the compile command line.
-  string(REGEX MATCHALL "-D([^\" ]+|\"[^\"]+\")" MPI_ALL_COMPILE_FLAGS ${MPI_COMPILE_CMDLINE})
+  string(REGEX MATCHALL "-D([^\" ]+|\"[^\"]+\")" MPI_ALL_COMPILE_FLAGS "${MPI_COMPILE_CMDLINE}")
   set(MPI_COMPILE_FLAGS_WORK)
   foreach(FLAG ${MPI_ALL_COMPILE_FLAGS})
     if (MPI_COMPILE_FLAGS_WORK)
@@ -100,17 +137,25 @@ elseif (MPI_COMPILE_CMDLINE)
   endforeach(FLAG)
 
   # Extract include paths from compile command line
-  string(REGEX MATCH "-I([^\" ]+|\"[^\"]+\")" MPI_INCLUDE_PATH ${MPI_COMPILE_CMDLINE})
-  string(REGEX REPLACE "^-I" "" MPI_INCLUDE_PATH ${MPI_INCLUDE_PATH})
-  string(REGEX REPLACE "//" "/" MPI_INCLUDE_PATH ${MPI_INCLUDE_PATH})
-
+  string(REGEX MATCHALL "-I([^\" ]+|\"[^\"]+\")" MPI_ALL_INCLUDE_PATHS "${MPI_COMPILE_CMDLINE}")
+  set(MPI_INCLUDE_PATH_WORK)
+  foreach(IPATH ${MPI_ALL_INCLUDE_PATHS})
+    string(REGEX REPLACE "^-I" "" IPATH ${IPATH})
+    string(REGEX REPLACE "//" "/" IPATH ${IPATH})
+    list(APPEND MPI_INCLUDE_PATH_WORK ${IPATH})
+  endforeach(IPATH)
+  
   # Extract linker paths from the link command line
-  string(REGEX MATCH "-L([^\" ]+|\"[^\"]+\")" MPI_LINK_PATH ${MPI_LINK_CMDLINE})
-  string(REGEX REPLACE "^-L" "" MPI_LINK_PATH ${MPI_LINK_PATH})
-  string(REGEX REPLACE "//" "/" MPI_LINK_PATH ${MPI_LINK_PATH})
+  string(REGEX MATCHALL "-L([^\" ]+|\"[^\"]+\")" MPI_ALL_LINK_PATHS "${MPI_LINK_CMDLINE}")
+  set(MPI_LINK_PATH)
+  foreach(LPATH ${MPI_ALL_LINK_PATHS})
+    string(REGEX REPLACE "^-L" "" LPATH ${LPATH})
+    string(REGEX REPLACE "//" "/" LPATH ${LPATH})
+    list(APPEND MPI_LINK_PATH ${LPATH})
+  endforeach(LPATH)
 
   # Extract linker flags from the link command line
-  string(REGEX MATCHALL "-Wl,([^\" ]+|\"[^\"]+\")" MPI_ALL_LINK_FLAGS ${MPI_LINK_CMDLINE})
+  string(REGEX MATCHALL "-Wl,([^\" ]+|\"[^\"]+\")" MPI_ALL_LINK_FLAGS "${MPI_LINK_CMDLINE}")
   set(MPI_LINK_FLAGS_WORK)
   foreach(FLAG ${MPI_ALL_LINK_FLAGS})
     if (MPI_LINK_FLAGS_WORK)
@@ -122,7 +167,7 @@ elseif (MPI_COMPILE_CMDLINE)
 
   # Extract the set of libraries to link against from the link command
   # line
-  string(REGEX MATCHALL "-l([^\" ]+|\"[^\"]+\")" MPI_LIBNAMES ${MPI_LINK_CMDLINE})
+  string(REGEX MATCHALL "-l([^\" ]+|\"[^\"]+\")" MPI_LIBNAMES "${MPI_LINK_CMDLINE}")
 
   # Determine full path names for all of the libraries that one needs
   # to link against in an MPI program
@@ -143,31 +188,23 @@ elseif (MPI_COMPILE_CMDLINE)
   # MPI_EXTRA_LIBRARY.
   list(LENGTH MPI_LIBRARIES MPI_NUMLIBS)
   if (MPI_NUMLIBS GREATER 0)
-    list(GET MPI_LIBRARIES 0 MPI_LIBRARY)
+    list(GET MPI_LIBRARIES 0 MPI_LIBRARY_WORK)
+    set(MPI_LIBRARY ${MPI_LIBRARY_WORK} CACHE FILEPATH "MPI library to link against" FORCE)
   else (MPI_NUMLIBS GREATER 0)
-    set(MPI_LIBRARY "MPI_LIBRARY-NOTFOUND")
+    set(MPI_LIBRARY "MPI_LIBRARY-NOTFOUND" CACHE STRING "MPI library to link against" FORCE)
   endif (MPI_NUMLIBS GREATER 0)
   if (MPI_NUMLIBS GREATER 1)
-    set(MPI_EXTRA_LIBRARY ${MPI_LIBRARIES})
-    list(REMOVE_AT MPI_EXTRA_LIBRARY 0)
+    set(MPI_EXTRA_LIBRARY_WORK ${MPI_LIBRARIES})
+    list(REMOVE_AT MPI_EXTRA_LIBRARY_WORK 0)
+    set(MPI_EXTRA_LIBRARY ${MPI_EXTRA_LIBRARY_WORK} CACHE STRING "Extra MPI libraries to link against" FORCE)
   else (MPI_NUMLIBS GREATER 1)
-    set(MPI_EXTRA_LIBRARY "MPI_EXTRA_LIBRARY-NOTFOUND")
+    set(MPI_EXTRA_LIBRARY "MPI_EXTRA_LIBRARY-NOTFOUND" CACHE STRING "Extra MPI libraries to link against" FORCE)
   endif (MPI_NUMLIBS GREATER 1)
 
   # Set up all of the appropriate cache entries
-  set(MPI_FOUND TRUE CACHE INTERNAL "Whether MPI was found" FORCE)
-
-  if (NOT MPI_FORCE_RECONFIGURE)
-    set(MPI_COMPILE_FLAGS ${MPI_COMPILE_FLAGS_WORK} CACHE STRING "MPI compilation flags")
-    set(MPI_INCLUDE_PATH ${MPI_INCLUDE_PATH} CACHE STRING "MPI include path")
-    set(MPI_LINK_FLAGS ${MPI_LINK_FLAGS_WORK} CACHE STRING "MPI linking flags")
-    set(MPI_LIBRARIES ${MPI_LIBRARIES} CACHE STRING "MPI libraries to link against, separated by semicolons")
-  else (NOT MPI_FORCE_RECONFIGURE)
-    set(MPI_COMPILE_FLAGS ${MPI_COMPILE_FLAGS_WORK} CACHE STRING "MPI compilation flags" FORCE)
-    set(MPI_INCLUDE_PATH ${MPI_INCLUDE_PATH} CACHE STRING "MPI include path" FORCE)
-    set(MPI_LINK_FLAGS ${MPI_LINK_FLAGS_WORK} CACHE STRING "MPI linking flags" FORCE)
-    set(MPI_LIBRARIES ${MPI_LIBRARIES} CACHE STRING "MPI libraries to link against, separated by semicolons" FORCE)
-  endif (NOT MPI_FORCE_RECONFIGURE)
+  set(MPI_COMPILE_FLAGS ${MPI_COMPILE_FLAGS_WORK} CACHE STRING "MPI compilation flags" FORCE)
+  set(MPI_INCLUDE_PATH ${MPI_INCLUDE_PATH_WORK} CACHE STRING "MPI include path" FORCE)
+  set(MPI_LINK_FLAGS ${MPI_LINK_FLAGS_WORK} CACHE STRING "MPI linking flags" FORCE)
 else (MPI_COMPILE_CMDLINE)
   find_path(MPI_INCLUDE_PATH mpi.h 
     /usr/local/include 
@@ -176,16 +213,16 @@ else (MPI_COMPILE_CMDLINE)
     /usr/local/mpi/include
     "C:/Program Files/MPICH/SDK/Include" 
     "$ENV{SystemDrive}/Program Files/MPICH2/include"
-    "C:/Program Files/Microsoft Compute Cluster Pack/Include"
+    "$ENV{SystemDrive}/Program Files/Microsoft Compute Cluster Pack/Include"
     )
   
-  # TODO: How do we know whether we're building 32-bit vs. 64-bit?
+  # TODO: How do we know whether we're building 32-bit vs. 64-bit for MS-MPI?
   find_library(MPI_LIBRARY 
     NAMES mpi mpich
     PATHS /usr/lib /usr/local/lib /usr/local/mpi/lib
     "C:/Program Files/MPICH/SDK/Lib" 
     "$ENV{SystemDrive}/Program Files/MPICH/SDK/Lib"
-    "C:/Program Files/Microsoft Compute Cluster Pack/Lib/i386"
+    "$ENV{SystemDrive}/Program Files/Microsoft Compute Cluster Pack/Lib/i386"
     )
   find_library(MPI_LIBRARY 
     NAMES mpich2
@@ -196,24 +233,11 @@ else (MPI_COMPILE_CMDLINE)
     NAMES mpi++
     PATHS /usr/lib /usr/local/lib /usr/local/mpi/lib
     "C:/Program Files/MPICH/SDK/Lib" 
-    "C:/Program Files/Microsoft Compute Cluster Pack/Lib/i386"
-    DOC "If a second MPI library is necessary, specify it here.")
+    DOC "Extra MPI libraries to link against.")
 
   set(MPI_COMPILE_FLAGS "" CACHE STRING "MPI compilation flags")
   set(MPI_LINK_FLAGS "" CACHE STRING "MPI linking flags")
-
-  if (MPI_EXTRA_LIBRARY)
-    set(MPI_LIBRARIES "${MPI_LIBRARY};${MPI_EXTRA_LIBRARY}" CACHE STRING "MPI libraries to link against, separated by semicolons")
-  else (MPI_EXTRA_LIBRARY)
-    set(MPI_LIBRARIES ${MPI_LIBRARY} CACHE STRING "MPI libraries to link against, separated by semicolons")
-  endif (MPI_EXTRA_LIBRARY)
-
-  if (MPI_LIBRARY)
-    set(MPI_FOUND TRUE CACHE INTERNAL "Whether MPI was found" FORCE)
-  else (MPI_LIBRARY)
-    set(MPI_FOUND FALSE CACHE INTERNAL "Whether MPI was found" FORCE)
-  endif (MPI_LIBRARY)
-endif (NOT MPI_FORCE_RECONFIGURE)
+endif (MPI_INCLUDE_PATH AND MPI_LIBRARY)
 
 # on BlueGene/L the MPI lib is named libmpich.rts.a, there also these additional libs are required
 if("${MPI_LIBRARY}" MATCHES "mpich.rts")
@@ -221,10 +245,22 @@ if("${MPI_LIBRARY}" MATCHES "mpich.rts")
    set(MPI_LIBRARY ${MPI_LIBRARY}  msglayer.rts devices.rts rts.rts devices.rts)
 endif("${MPI_LIBRARY}" MATCHES "mpich.rts")
 
-set(MPI_LIBRARY ${MPI_LIBRARY} CACHE INTERNAL "MPI library to link against. Deprecated: use MPI_LIBRARIES instead")
-set(MPI_EXTRA_LIBRARY ${MPI_EXTRA_LIBRARY} CACHE INTERNAL "Second MPI library to link against. Deprecated: use MPI_LIBRARIES instead")
+# Set up extra variables to conform to 
+if (MPI_EXTRA_LIBRARY)
+  set(MPI_LIBRARIES ${MPI_LIBRARY} ${MPI_EXTRA_LIBRARY})
+else (MPI_EXTRA_LIBRARY)
+  set(MPI_LIBRARIES ${MPI_LIBRARY})
+endif (MPI_EXTRA_LIBRARY)
+
+if (MPI_INCLUDE_PATH AND MPI_LIBRARY)
+  set(MPI_FOUND TRUE)
+else (MPI_INCLUDE_PATH AND MPI_LIBRARY)
+  set(MPI_FOUND FALSE)
+endif (MPI_INCLUDE_PATH AND MPI_LIBRARY)
 
 include(FindPackageHandleStandardArgs)
 # handle the QUIETLY and REQUIRED arguments 
 find_package_handle_standard_args(MPI DEFAULT_MSG MPI_LIBRARY MPI_INCLUDE_PATH)
-mark_as_advanced(MPI_INCLUDE_PATH MPI_COMPILE_FLAGS MPI_LINK_FLAGS MPI_LIBRARIES)
+
+mark_as_advanced(MPI_INCLUDE_PATH MPI_COMPILE_FLAGS MPI_LINK_FLAGS MPI_LIBRARY 
+  MPI_EXTRA_LIBRARY)