add _format key to MPIPreferences (#648)

Author: simonbyrne

docs/src/configuration.md

@@ -65,6 +65,7 @@ Preferences are merged across the Julia load path, such that it is feasible to p
 
    ```toml
    [MPIPreferences]
+   _format = "1.0"
    abi = "OpenMPI"
    binary = "system"
    libmpi = "/software/mpi/lib/libmpi.so"
@@ -78,6 +79,7 @@ Preferences are merged across the Julia load path, such that it is feasible to p
    MPIPreferences = "3da0fdf6-3ccc-4f1b-acd9-58baa6c99267"
 
    [preferences.MPIPreferences]
+   _format = "1.0"
    abi = "OpenMPI"
    binary = "system"
    libmpi = "/software/mpi/lib/libmpi.so"
@@ -135,7 +137,7 @@ The test suite can also be modified by the following variables:
 
 - `JULIA_MPI_TEST_NPROCS`: How many ranks to use within the tests
 - `JULIA_MPI_TEST_ARRAYTYPE`: Set to `CuArray` or `ROCArray` to test the CUDA-aware interface with
-  [`CUDA.CuArray`](https://github.com/JuliaGPU/CUDA.jl) or the ROCm-aware interface with 
+  [`CUDA.CuArray`](https://github.com/JuliaGPU/CUDA.jl) or the ROCm-aware interface with
   [`AMDGPU.ROCArray`](https://github.com/JuliaGPU/AMDGPU.jl) or buffers.
 - `JULIA_MPI_TEST_BINARY`: Check that the specified MPI binary is used for the tests
 - `JULIA_MPI_TEST_ABI`: Check that the specified MPI ABI is used for the tests

docs/src/reference/mpipreferences.md

@@ -1,6 +1,7 @@
 # MPIPreferences.jl
 
-MPIPreferences.jl is a small package used for selecting MPI implementations.
+MPIPreferences.jl is a small package based on [Preferences.jl](https://github.com/JuliaPackaging/Preferences.jl/) for selecting MPI implementations.
+These choices are compile-time constants, and so any changes will require a Julia restart.
 
 ## Consts
 
@@ -21,3 +22,17 @@ MPIPreferences.use_jll_binary
 ```@docs
 MPIPreferences.identify_abi
 ```
+
+## Preferences schema
+
+MPIPreferences utilizes the following keys to store information in the Preferences key-value store.
+
+- `_format`: the version number of the schema. Currently only `"1.0"` is supported.
+- `binary`: the choice of binary. This should be one of the strings listed in [`MPIPreferences.binary`](@ref).
+
+If `binary == "system"`, then the following keys are also required (otherwise they have no effect):
+- `libmpi`: the filename or path of the MPI dynamic library.
+- `abi`: The ABI of the MPI implementation. This should be one of the strings listed in [`MPIPreferences.abi`](@ref).
+- `mpiexec`: either
+  - a string corresponding to the MPI launcher executable
+  - an array of strings, with the first entry being the executable and remaining entried being additional flags that should be used with the executable.

lib/MPIPreferences/src/MPIPreferences.jl

@@ -2,6 +2,10 @@ module MPIPreferences
 
 using Preferences, Libdl
 
+if !(VersionNumber(@load_preference("_format", "1.0")) <= v"1.0")
+    error("The preferences attached to MPIPreferences are incompatible with this version of the package.")
+end
+
 """
     MPIPreferences.binary :: String
 
@@ -19,7 +23,7 @@ const binary = @load_preference("binary", Sys.iswindows() ? "MicrosoftMPI_jll" :
 """
     MPIPreferences.abi :: String
 
-The ABI of the currently selected binary. Supported values are:
+The ABI (application binary interface) of the currently selected binary. Supported values are:
 
 - `"MPICH"`: MPICH-compatible ABI (https://www.mpich.org/abi/)
 - `"OpenMPI"`: Open MPI compatible ABI (Open MPI, IBM Spectrum MPI, Fujitsu MPI)
@@ -62,6 +66,7 @@ function use_jll_binary(binary = Sys.iswindows() ? "MicrosoftMPI_jll" : "MPICH_j
     binary in ["MicrosoftMPI_jll", "MPICH_jll", "OpenMPI_jll", "MPItrampoline_jll"] ||
         error("Unknown jll: $binary")
     set_preferences!(MPIPreferences,
+        "_format" => "1.0",
         "binary" => binary,
         "libmpi" => nothing,
         "abi" => nothing,
@@ -140,6 +145,7 @@ function use_system_binary(;
         mpiexec = collect(mpiexec)
     end
     set_preferences!(MPIPreferences,
+        "_format" => "1.0",
         "binary" => binary,
         "libmpi" => libmpi,
         "abi" => abi,