Add convenience function set_libraries! (#1115)

* add convenience function set_libraries! * format * fix typo * fix docs * move function to helpers.jl * move back again * Add API.set_libraries! to configuration doc * remove unused not_low_level_api * fix typo * restore accidently pushed change * add cross-reference * add comma --------- Co-authored-by: Mark Kittisopikul <[email protected]> Co-authored-by: Mark Kittisopikul <[email protected]>
JuliaIO · Sep 24, 2023 · 625555b · 625555b
1 parent 703cd56
commit 625555b
Show file tree

Hide file tree

Showing 6 changed files with 63 additions and 30 deletions.
diff --git a/docs/Manifest.toml b/docs/Manifest.toml
@@ -116,31 +116,31 @@ uuid = "7b1f6079-737a-58dc-b8bc-7a2ca5c1b5ee"
 deps = ["HDF5", "bitshuffle_jll"]
 path = "../filters/H5Zbitshuffle"
 uuid = "51b4e782-877f-4ccf-958a-27bf628210da"
-version = "0.1.1"
+version = "0.1.2"
 
 [[deps.H5Zblosc]]
 deps = ["Blosc", "HDF5"]
 path = "../filters/H5Zblosc"
 uuid = "c8ec2601-a99c-407f-b158-e79c03c2f5f7"
-version = "0.1.1"
+version = "0.1.2"
 
 [[deps.H5Zbzip2]]
 deps = ["CodecBzip2", "HDF5"]
 path = "../filters/H5Zbzip2"
 uuid = "094576f2-1e46-4c84-8e32-c46c042eaaa2"
-version = "0.1.0"
+version = "0.1.1"
 
 [[deps.H5Zlz4]]
 deps = ["CodecLz4", "HDF5"]
 path = "../filters/H5Zlz4"
 uuid = "eb20ec05-5464-47b5-ba41-098e3c1068a3"
-version = "0.1.0"
+version = "0.1.1"
 
 [[deps.H5Zzstd]]
 deps = ["CodecZstd", "HDF5"]
 path = "../filters/H5Zzstd"
 uuid = "f6f2d980-1ec6-471c-a70d-0270e22f1103"
-version = "0.1.0"
+version = "0.1.1"
 
 [[deps.HDF5]]
 deps = ["Compat", "HDF5_jll", "Libdl", "MPIPreferences", "Mmap", "Preferences", "Printf", "Random", "Requires", "UUIDs"]
@@ -154,9 +154,9 @@ weakdeps = ["MPI"]
 
 [[deps.HDF5_jll]]
 deps = ["Artifacts", "CompilerSupportLibraries_jll", "JLLWrappers", "LLVMOpenMP_jll", "LazyArtifacts", "LibCURL_jll", "Libdl", "MPICH_jll", "MPIPreferences", "MPItrampoline_jll", "MicrosoftMPI_jll", "OpenMPI_jll", "OpenSSL_jll", "TOML", "Zlib_jll", "libaec_jll"]
-git-tree-sha1 = "10c72358aaaa5cd6bc7cc39b95e6eadf92f5a336"
+git-tree-sha1 = "38c8874692d48d5440d5752d6c74b0c6b0b60739"
 uuid = "0234f1f7-429e-5d53-9886-15a909be8d59"
-version = "1.14.2+0"
+version = "1.14.2+1"
 
 [[deps.IOCapture]]
 deps = ["Logging", "Random"]
@@ -223,9 +223,9 @@ version = "1.9.4+0"
 
 [[deps.MPI]]
 deps = ["Distributed", "DocStringExtensions", "Libdl", "MPICH_jll", "MPIPreferences", "MPItrampoline_jll", "MicrosoftMPI_jll", "OpenMPI_jll", "PkgVersion", "PrecompileTools", "Requires", "Serialization", "Sockets"]
-git-tree-sha1 = "32cafbe56c7f0b7160a1a6c492773af66c0b722f"
+git-tree-sha1 = "df53d0e1e0dbebf2315f4cd35e13e52ad43416c2"
 uuid = "da04e1cc-30fd-572f-bb4f-1f8673147195"
-version = "0.20.14"
+version = "0.20.15"
 
     [deps.MPI.extensions]
     AMDGPUExt = "AMDGPU"

diff --git a/docs/make.jl b/docs/make.jl
@@ -6,19 +6,6 @@ using H5Zlz4
 using H5Zzstd
 using MPI  # needed to generate docs for parallel HDF5 API
 
-# Used in index.md to filter the autodocs list
-not_low_level_api(m::Method) = !endswith(String(m.file), "src/api.jl")
-not_low_level_api(f::Function) = all(not_low_level_api, methods(f))
-not_low_level_api(o) = true
-
-# defined on separate page
-not_low_level_api(::Type{<:HDF5.Properties}) = false
-
-# Manually-defined low-level API (in source file src/api_helpers.jl)
-not_low_level_api(::typeof(HDF5.API.h5p_get_class_name)) = false
-not_low_level_api(::typeof(HDF5.API.h5t_get_member_name)) = false
-not_low_level_api(::typeof(HDF5.API.h5t_get_tag)) = false
-
 DocMeta.setdocmeta!(HDF5, :DocTestSetup, :(using HDF5); recursive=true)
 
 makedocs(;

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -63,6 +63,13 @@ set_preferences!(
     "libhdf5_hl" => "/usr/lib/x86_64-linux-gnu/hdf5/mpich/libhdf5_hl.so", force = true)
 ```
 
+Alternatively, HDF5.jl provides a convenience function [`HDF5.API.set_libraries!`](@ref) that can be used as follows:
+```julia
+using HDF5
+
+HDF5.API.set_libraries!("/usr/lib/x86_64-linux-gnu/hdf5/mpich/libhdf5.so", "/usr/lib/x86_64-linux-gnu/hdf5/mpich/libhdf5_hl.so")
+```
+Going back to the default, i.e. deleting the preferences again, can be done by calling `HDF5.API.set_libraries!()`.
 If HDF5 cannot be loaded, it may be useful to use the UUID to change these settings:
 
 ```julia

diff --git a/docs/src/interface/configuration.md b/docs/src/interface/configuration.md
@@ -23,4 +23,10 @@ SHOW_TREE_MAX_DEPTH
 get_context_property
 CONTEXT
 HDF5Context
-```
+```
+
+## System Libraries
+
+```@docs
+API.set_libraries!
+```
diff --git a/docs/src/mpi.md b/docs/src/mpi.md
@@ -45,13 +45,9 @@ preferences `libhdf5` and `libhdf5_hl` to the full path, where the parallel HDF5
 This can be done by:
 
 ```julia
-julia> using Preferences, UUIDs
+julia> using HDF5
 
-julia> set_preferences!(
-           UUID("f67ccb44-e63f-5c2f-98bd-6dc0ccc4ba2f"), # UUID of HDF5.jl
-           "libhdf5" => "/path/to/your/libhdf5.so",
-           "libhdf5_hl" => "/path/to/your/libhdf5_hl.so",
-           force = true)
+julia> HDF5.API.set_libraries!("/path/to/your/libhdf5.so", "/path/to/your/libhdf5_hl.so")
 ```
 
 ### 3. Loading MPI-enabled HDF5

diff --git a/src/api/api.jl b/src/api/api.jl
@@ -2,7 +2,8 @@ module API
 
 using Libdl: dlopen, dlclose, dlpath, dlsym, RTLD_LAZY, RTLD_NODELETE
 using Base: StringVector
-using Preferences: @load_preference
+using Preferences: @load_preference, delete_preferences!, set_preferences!
+using UUIDs: UUID
 
 const _PREFERENCE_LIBHDF5 = @load_preference("libhdf5", nothing)
 const _PREFERENCE_LIBHDF5_HL = @load_preference("libhdf5_hl", nothing)
@@ -22,6 +23,42 @@ else
     libhdf5_size = filesize(dlpath(libhdf5))
 end
 
+const HDF5_JL_UUID = UUID("f67ccb44-e63f-5c2f-98bd-6dc0ccc4ba2f")
+const HDF5_JLL_JL_UUID = UUID("0234f1f7-429e-5d53-9886-15a909be8d59")
+
+"""
+    set_libraries!(libhdf5 = nothing, libhdf5_hl = nothing; force = true)
+
+Convenience function to set the preferences for a system-provided HDF5 library.
+Pass the paths pointing to the libraries `libhdf5` and `libhdf5_hl` as strings
+to set the preference. If `libhdf5` and `libhdf5_hl` are `nothing` use the default,
+i.e. the binaries provided by HDF5_jll.jl.
+"""
+function set_libraries!(libhdf5=nothing, libhdf5_hl=nothing; force=true)
+    if isnothing(libhdf5) && isnothing(libhdf5_hl)
+        delete_preferences!(HDF5_JL_UUID, "libhdf5"; force)
+        delete_preferences!(HDF5_JL_UUID, "libhdf5_hl"; force)
+        delete_preferences!(HDF5_JLL_JL_UUID, "libhdf5_path", "libhdf5_hl_path"; force)
+        @info "The libraries from HDF5_jll will be used."
+    elseif isnothing(libhdf5) || isnothing(libhdf5_hl)
+        throw(
+            ArgumentError(
+                "Specify either no positional arguments or both positional arguments."
+            )
+        )
+    else
+        isfile(libhdf5) || throw(ArgumentError("$libhdf5 is not a file that exists."))
+        isfile(libhdf5_hl) || throw(ArgumentError("$libhdf5_hl is not a file that exists."))
+        set_preferences!(HDF5_JL_UUID, "libhdf5" => libhdf5; force)
+        set_preferences!(HDF5_JL_UUID, "libhdf5_hl" => libhdf5_hl; force)
+        # Also set the HDF5_jll override settings in case some other package tries to use HDF5_jll
+        set_preferences!(
+            HDF5_JLL_JL_UUID, "libhdf5_path" => libhdf5, "libhdf5_hl_path" => libhdf5_hl
+        )
+    end
+    @info "Please restart Julia and reload HDF5.jl for the library changes to take effect"
+end
+
 include("lock.jl")
 include("types.jl")
 include("error.jl")