zarrs_ffi
C/C++ bindings for the zarrs rust crate
zarrs_ffi

Latest Version zarrs documentation zarrs documentation msrv build

C/C++ bindings for the zarrs crate, a Rust library for the Zarr storage format for multidimensional arrays and metadata.

zarrs_ffi is a single header library: zarrs.h (docs).

Currently zarrs_ffi only supports a small subset of the zarrs API.

A changelog can be found here.

Example

{C++}
#include "zarrs.h"
void main() {
// Open a filesystem store pointing to a zarr hierarchy
ZarrsStorage storage = nullptr;
zarrs_assert(zarrsCreateStorageFilesystem("/path/to/hierarchy.zarr", &storage));
// Open an array in the hierarchy
ZarrsArray array = nullptr;
zarrsOpenArrayRW(storage, "/array", metadata, &array);
// Get the array dimensionality
size_t dimensionality;
zarrs_assert(zarrsArrayGetDimensionality(array, &dimensionality));
assert(dimensionality == 2);
// Retrieve the decoded bytes of the chunk at [0, 0]
size_t indices[] = {0, 0};
size_t chunk_size;
zarrs_assert(zarrsArrayGetChunkSize(array, 2, indices, &chunk_size));
std::unique_ptr<uint8_t[]> chunk_bytes(new uint8_t[chunk_size]);
zarrs_assert(zarrsArrayRetrieveChunk(array, 2, indices, chunk_size, chunk_bytes.get()));
}

See a more comprehensive example in the examples directory.

CMake Quickstart

  1. Install the Rust compiler (and cargo).
  2. Put Findzarrs.cmake in your CMAKE_MODULE_PATH
  3. find_package(zarrs <version> REQUIRED COMPONENTS zarrs/bz2)
    • Replace <version> with the latest release: Latest Version (e.g., 0.8 or 0.8.4)
    • zarrs is retrieved from GitHub using FetchContent and built using corrosion
    • Components are optional zarrs codecs
  4. the zarrs_ffi library is available as the zarrs::zarrs or zarrs::zarrs-static target

A complete CMake example can be found in examples/cmake_project.

Manual Build

Basic Build

Building generates a header, and a platform-dependent static and dynamic library.

cargo build --release --features cbindgen # -> zarrs.h and target/release/[lib]zarrs_ffi{.a,.so,.dll,.dylib}

zarrs.h is only re-generated if the cbindgen feature is enabled.

Enabling SIMD intrinsics

Encoding and decoding performance may be improved with avx2/sse2 enabled (if supported). Compile with either of:

  • RUSTFLAGS="-C target-cpu=native"
  • RUSTFLAGS="-C target-feature=+avx2,+sse2"

Enabling non-default zarrs codecs

Non-default zarrs codecs (see zarrs crate features) can be enabled with the all_codecs feature. Alternatively, individual codecs can be enabled by passing them as feature flags. For example:

cargo build --release --features cbindgen --features zarrs/zstd,zarrs/bitround,zarrs/zfp,zarrs/bz2,zarrs/pcodec,zarrs/gdeflate

Licence

zarrs_ffi is licensed under either of

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.