Skip to content

Latest commit

 

History

History
162 lines (115 loc) · 4.48 KB

README.md

File metadata and controls

162 lines (115 loc) · 4.48 KB
Raw

RustRocks

crates.io badge DOCS.RS badge Linux Build Status macOS Build Status Windows Build Status

Another RocksDB binding for Rust. Documentation

Make RocksDB really rocks!

  • Static link against RocksDB 6.7.3 (git submodules)
  • Dynamic link tested:
    • macOS homebrew
    • Windows 10, VS 2019 with vcpkg
    • ArchLinux pacman, both x86_64 and aarch64(ODroid-C2)
    • Ubuntu 18.04 (rocksdb5.8 branch), both x86_64 and aarch64(RPi 3)
    • Ubuntu 20.04 (rocksdb5.17 branch)

Installation

Dynamicly link RocksDB:

[dependencies]
rocks = "0.1"

Static link against RocksDB(with snappy enabled by default):

[dependencies.rocks]
version = "0.1"
default-features = false
features = ["static-link"]

With all static features(all compression types):

[dependencies.rocks]
version = "0.1"
default-features = false
features = ["full"]

How to compile

Feel free to refer Travic-CI, AppVeyor and Github Actions configuration files.

Static Link

$ git submodule update --init --recursive
$ cargo test --features static-link -- --test-threads 1
(This will build with snappy as the only compression supported)

$ cargo test --features full -- --test-threads 1
(This will build with all compression supported)

Dynamic Link

For macOS(with RocksDB installed via brew):

$ brew install rocksdb
$ cargo test -- --nocapture --test-threads 1

For Linux:

(install rocksdb via package manager or make & install)
$ sudo apt install lld
(NOTE: gcc-ld can't handle circular references while linking.)
(for more, refer the last section of README)
$ RUSTFLAGS="-C link-arg=-fuse-ld=lld" cargo test -- --test-threads 1

Use environment variables if rocksdb is installed to non-default directory:

LD_LIBRARY_PATH=/usr/local/lib LIBRARY_PATH=/usr/local/lib CXXFLAGS=-I/usr/local/include

Ubuntu LTS

RocksDB changes its API often, so rust-rocks use different branch to support Ubuntu LTS.

> sudo apt install librocksdb-dev libsnappy-dev

You also need lld form official source or http://apt.llvm.org/.

Branches:

  • rocksdb5.8 (18.04 LTS)
  • rocksdb5.17 (20.04 LTS)

Windows

You need VS 2017 or VS 2019, and install RocksDB via vcpkg.

FAQ

Feel free to Open a New Issue.

List current supported compression types

$ cargo run --example it-works
RocksDB: 6.7.3
Compression Supported:
  - NoCompression
  - SnappyCompression
  - ZlibCompression
  - BZip2Compression
  - LZ4Compression
  - LZ4HCCompression
  - ZSTD
  - ZSTDNotFinalCompression

Development

Bindgen:

$ cd rocks-sys
$ PATH="/usr/local/opt/llvm/bin:$PATH" make
(this will regenerate the bindgen c.rs)

Known bugs

Linking error under Linux

  • rust-rocks exports rust functions to c++, so there are circular references while linking
  • GCC requires that you put the object files and libraries in the order that they depend on each other
  • Rust will not wrap user crates in --start-group and --end-group
  • So circular references will be errors.
  • Can be fixed by using lld as linker, RUSTFLAGS="-C link-arg=-fuse-ld=lld"
  • Can be fixed by manually organising link arguments
    • librocks, then librocks_sys, then librocks again

Minor memory leaks

  • The raw pointers are created on the fly, should be impled via lazy_static and wrapped in trait objects
    • ColumnFamilyOptions::comparator: const Comparator*
    • ColumnFamilyOptions::compaction_filter: const CompactionFilter*

Iterator leaks lifetime

Ref: #15

  • While doing a for-traverse: That's OK
  • While collecting for later use: Clone the keys and values