hdf5-rust

HDF5 的 Rust 实现。

“hdf5-metno” crate（也称为“hdf5”的前分叉名称）为 HDF5 库 API 提供线程安全 Rust 绑定和高层包装。其中一些特性包括：

• 通过可重入互斥锁保证非线程安全 libhdf5 构建的线程安全。
• 大多数 HDF5 类型的本地表示，包括可变长度字符串和数组。
• 自动将用户结构和枚举映射到 HDF5 类型的 derive-macro。
• 通过 ndarray 提供多维数组读取/写入接口。

还提供了直接的低级绑定，并在 hdf5-sys crate 中提供。

需要版本 1.8.4 或更高版本的 HDF5 库。

分叉

这是 https://github.com/aldanor/hdf5-rust 的分叉，用于发布 crate 的新版本。这包括将 crate 名称更改为允许在 crates.io 上发布。为了保持向后兼容性，请考虑在您的 Cargo.toml 中使用以下内容：

hdf5 = { package = "hdf5-metno", version = "0.9.0" }

示例

#[cfg(feature = "blosc")]
use hdf5::filters::blosc_set_nthreads;
use hdf5::{File, H5Type, Result};
use ndarray::{arr2, s};

#[derive(H5Type, Clone, PartialEq, Debug)] // register with HDF5
#[repr(u8)]
pub enum Color {
    R = 1,
    G = 2,
    B = 3,
}

#[derive(H5Type, Clone, PartialEq, Debug)] // register with HDF5
#[repr(C)]
pub struct Pixel {
    xy: (i64, i64),
    color: Color,
}

impl Pixel {
    pub fn new(x: i64, y: i64, color: Color) -> Self {
        Self { xy: (x, y), color }
    }
}

fn write_hdf5() -> Result<()> {
    use Color::*;
    let file = File::create("pixels.h5")?; // open for writing
    let group = file.create_group("dir")?; // create a group
    #[cfg(feature = "blosc")]
    blosc_set_nthreads(2); // set number of blosc threads
    let builder = group.new_dataset_builder();
    #[cfg(feature = "blosc")]
    let builder = builder.blosc_zstd(9, true); // zstd + shuffle
    let ds = builder
        .with_data(&arr2(&[
            // write a 2-D array of data
            [Pixel::new(1, 2, R), Pixel::new(2, 3, B)],
            [Pixel::new(3, 4, G), Pixel::new(4, 5, R)],
            [Pixel::new(5, 6, B), Pixel::new(6, 7, G)],
        ]))
        // finalize and write the dataset
        .create("pixels")?;
    // create an attr with fixed shape but don't write the data
    let attr = ds.new_attr::<Color>().shape([3]).create("colors")?;
    // write the attr data
    attr.write(&[R, G, B])?;
    Ok(())
}

fn read_hdf5() -> Result<()> {
    use Color::*;
    let file = File::open("pixels.h5")?; // open for reading
    let ds = file.dataset("dir/pixels")?; // open the dataset
    assert_eq!(
        // read a slice of the 2-D dataset and verify it
        ds.read_slice::<Pixel, _, _>(s![1.., ..])?,
        arr2(&[
            [Pixel::new(3, 4, G), Pixel::new(4, 5, R)],
            [Pixel::new(5, 6, B), Pixel::new(6, 7, G)],
        ])
    );
    let attr = ds.attr("colors")?; // open the attribute
    assert_eq!(attr.read_1d::<Color>()?.as_slice().unwrap(), &[R, G, B]);
    Ok(())
}

fn main() -> Result<()> {
    write_hdf5()?;
    read_hdf5()?;
    Ok(())
}

兼容性

平台

hdf5 crate 已在以下平台上运行：Linux、macOS、Windows（已在：Ubuntu 16.04、18.04 和 20.04；Windows Server 2019，使用 MSVC 和 GNU 工具链；macOS Catalina）。

Rust

hdf5 crate 在所有三个官方发布渠道上持续进行测试，并需要一个相当新的 Rust 编译器（例如，版本 1.80 或更高版本）。

HDF5

所需 HDF5 版本为 1.8.4 或更高。库不必启用线程安全选项即可使用户代码线程安全。

支持并测试了各种 HDF5 安装选项：通过包管理器如 homebrew 和 apt；Windows 上的系统级安装；从官方渠道和 conda-forge 进行 conda 安装。在 Linux 和 macOS 上，支持并测试了 OpenMPI 和 MPICH 并行构建。

HDF5 C库也可以从源代码构建并静态链接，通过启用hdf5-sys/static功能（需要CMake）。

构建

HDF5版本

用于构建hdf5-sys和hdf5crate的构建脚本会检查它们正在链接的HDF5库的实际版本，并且在编译时可能会根据条件启用或禁用某些功能。虽然这允许在单个代码库中支持多个HDF5版本，但用户在决定使用低级FFI绑定时应注意这一点。

环境变量

如果设置了HDF5_DIR，构建脚本将只在指定位置查找HDF5头文件和二进制文件（即在$HDF5_DIR/include下查找头文件）。

如果设置了HDF5_VERSION，构建脚本将检查库版本是否与指定的版本字符串匹配；在某些情况下，它还可以由构建脚本用于帮助定位库（例如，在macOS上通过Homebrew安装了1.8和1.10）。

conda

可以链接到hdf5conda包；一些注意事项和技巧

• 将HDF5_DIR指向conda环境根目录。
• 构建脚本了解conda环境的布局细节，并将相应地调整路径（例如，Windows环境中的Library子文件夹）。
• 在Windows上，环境中的bin文件夹必须位于PATH中（或者可以在运行cargo之前激活环境）。
• 在Linux / macOS上，建议设置rpath，例如，通过设置RUSTFLAGS="-C link-args=-Wl,-rpath,$HDF5_DIR/lib"。
• 对于macOS上旧版本的HDF5 conda包，可能还需要设置DYLD_FALLBACK_LIBRARY_PATH="$HDF5_DIR/lib"。

Linux

构建脚本将首先尝试使用pkg-config，这对于HDF5较新版本通常不需要进一步调整。然后，构建脚本还会在Ubuntu上apt安装后可以找到HDF5的几个标准位置中查找HDF5。

macOS

在macOS上，如果Homebrew可用，构建脚本将尝试通过Homebrew定位HDF5。如果同时安装了1.8和1.10，并且它们都可用，除非设置了HDF5_VERSION，否则默认使用1.10版本。

Windows

hdf5crate完全支持MSVC工具链，允许使用HDF5的官方发布版，这通常是推荐的方案。尽管如此，之前的实验表明，在gnu目标上所有测试都通过，只需小心构建HDF5二进制文件和配置构建环境即可。

在Windows上构建时需要注意的几点

• hdf5.dll在构建时间和运行时（在gnu和msvc中）必须在搜索路径中可用。通常需要将HDF5安装的bin文件夹添加到PATH中。如果使用官方HDF5发布版（仅限msvc），通常由安装程序自动完成此操作。
• msvc：安装的 Visual Studio 版本应与 HDF5 二进制文件匹配（2013 或 2015）。请注意，不需要运行 vcvars 脚本；Rust 构建系统将负责这一点。
• 在为任何目标构建时，请确保搜索路径中没有冲突（例如，MinGW 工具链的一些二进制文件可能会覆盖 MSVS 可执行文件，反之亦然）。
• 对于 gnu 目标，推荐的平台是 MinGW-GCC 的 TDM 发行版，因为它包含 32 位和 64 位的 bintools。
• 对于 msvc 目标，推荐的环境是 VS2015 x64，因为这与 CI 构建配置相匹配，然而 VS2013 和 x86 也能同样工作。

许可证

hdf5 库主要在 MIT 许可证和 Apache 许可证（版本 2.0）的条款下分发。有关详细信息，请参阅 LICENSE-APACHE 和 LICENSE-MIT。