GitHub Workflow Status

HTSlib bindings for Rust

This library provides HTSlib bindings and a high level Rust API for reading and writing BAM files.

To clone this repository, issue

$ git clone --recursive https://github.com/rust-bio/rust-htslib.git

ensuring that the HTSlib submodule is fetched, too. If you only want to use the library, there is no need to clone the repository. Go on to the Usage section in this case.

Requirements

rust-htslib comes with pre-built bindings to htslib for Mac and Linux. You will need a C toolchain compatible with the cc crate. The build script for this crate will automatically build a link htslib.

Usage

Add this to your Cargo.toml:

[dependencies]
rust-htslib = "*"

By default rust-htslib links to bzip2-sys and lzma-sys for full CRAM support. If you do not need CRAM support, or you do need to support CRAM files with these compression methods, you can deactivate these features to reduce you dependency count:

[dependencies]
rust-htslib = { version = "*", default-features = false }

rust-htslib has optional support for serde, to allow (de)serialization of bam::Record via any serde-supported format.

Http access to files is available with the curl feature.

Beta-level S3 and Google Cloud Storge support is available with the s3 and gcs features.

rust-htslib can optionally use bindgen to generate bindings to htslib. This can slow down the build substantially. Enabling the bindgen feature will cause hts-sys to use a create a binding file for your architecture. Pre-built bindings are supplied for Mac and Linux. The bindgen feature on Windows is untested - please file a bug if you need help.

[dependencies]
rust-htslib = { version = "*", features = ["serde_feature"] }

For more information, please see the docs.

Alternatives

There's noodles by Michael Macias which implements a large part of htslib's C functionality in pure Rust (still experimental though).

Authors

For other contributors, see here.

License