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