Skip to content

Installation

rayforce builds against a local checkout of the RayforceDB core. The build script compiles the core into a static library (librayforce.a) and statically links it, so there is nothing to install at runtime.

Prerequisites

  • A recent Rust toolchain (edition 2021, rustc 1.74 or newer). Install via rustup.
  • A C toolchain — make and clang — to build the RayforceDB core.
  • libclang, required by bindgen to generate the raw FFI bindings.
  • A RayforceDB core checkout to link against (see below).

macOS: LIBCLANG_PATH

On macOS bindgen may not find libclang automatically. Point it at your installation, for example:

export LIBCLANG_PATH="$(brew --prefix llvm)/lib"

The repository's .cargo/config.toml is the place to set this permanently for local builds.

Building against a local core

The build links a local RayforceDB core checkout. Point the RAYFORCE_SRC environment variable at it; it defaults to ~/rayforce. The build script runs the core's make lib to produce librayforce.a, then links it.

# Clone the core somewhere, e.g. your home directory.
git clone https://github.com/RayforceDB/rayforce.git ~/rayforce

# Point the build at it (default is ~/rayforce, so this is optional there).
export RAYFORCE_SRC=~/rayforce

# Build and test the bindings.
cargo build
cargo test

Tests run single-threaded

The engine runs on a single thread with one live runtime per process, so the test suite is serialized. Run it with RUST_TEST_THREADS=1 (or via the crate's serial_test setup) if you invoke tests directly.

Adding the dependency

Add rayforce to your crate:

cargo add rayforce

or in Cargo.toml:

[dependencies]
rayforce = "0.1"

The chrono feature (default)

The chrono feature is enabled by default. It adds conversions between RayforceDB temporal types and chrono types — NaiveDate ↔ date, NaiveTime ↔ time, and DateTime<Utc> ↔ timestamp (the RayforceDB epoch is 2000-01-01).

To build without it, disable default features:

[dependencies]
rayforce = { version = "0.1", default-features = false }

Next steps