diff --git a/docs/Manifest.toml b/docs/Manifest.toml index 135bcd050..59cd6eaa9 100644 --- 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 index 54cc1fd40..286f5f020 100644 --- 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 index 46b8abd48..06782200c 100644 --- 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 index f6156cc88..fb0ea4c39 100644 --- 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 -``` \ No newline at end of file +``` + +## System Libraries + +```@docs +API.set_libraries! +``` diff --git a/docs/src/mpi.md b/docs/src/mpi.md index abf4e0260..0da4f4504 100644 --- 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 index e10edd9f7..a80d3ff74 100644 --- 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")