Deprecate old mpiexec method (#874)

Keep only the method which returns the path to the `mpiexec` executable, which
is the one JLLs prefer nowadays, too.

docs/make.jl

@@ -39,7 +39,7 @@ for (example_title, example_md) in EXAMPLES
  println(mdfile, "```")
  println(mdfile, "> mpiexecjl -n 4 julia $example_jl")
  cd(@__DIR__) do
- write(mdfile, mpiexec(cmd -> read(`$cmd -n 4 $(Base.julia_cmd()) --project $example_jl`)))
+ write(mdfile, read(`$(mpiexec()) -n 4 $(Base.julia_cmd()) --project $example_jl`))
  end
  println(mdfile, "```")
  end

lib/MPIPreferences/src/system.jl

@@ -8,7 +8,8 @@ module System
  const preloads_env_switch = @load_preference("preloads_env_switch")
  const mpiexec_path = @load_preference("mpiexec")
  mpiexec(;adjust_PATH=true, adjust_LIBPATH=true) = `$mpiexec_path`
- mpiexec(f;adjust_PATH=true, adjust_LIBPATH=true) = f(`$mpiexec_path`)
+ # The following method may be removed in future releases.
+ Base.@deprecate mpiexec(f;adjust_PATH=true, adjust_LIBPATH=true) f(mpiexec())
 
  libmpi_handle = C_NULL
  function __init__()

src/environment.jl

@@ -1,12 +1,12 @@
 """
- mpiexec(fn)
+ mpiexec()
 
-A wrapper function for the MPI launcher executable. Calls `fn(cmd)`, where `cmd` is a `Cmd` object of the MPI launcher.
+A wrapper function for the MPI launcher executable. Returns a `Cmd` object pointing to the MPI launcher.
 
 # Usage
 
 ```jldoctest
-julia> mpiexec(cmd -> run(`\$cmd -n 3 echo hello world`));
+julia> run(`\$(mpiexec()) -n 3 echo hello world`);
 hello world
 hello world
 hello world