Installation
This page covers how to set up a development environment for Ripple, including OCaml toolchain installation, dependency management, and build verification.
Prerequisites
Ripple requires OCaml 5.1.0 or later and the following system-level dependencies:
| Dependency | Version | Purpose |
|---|---|---|
| OCaml | >= 5.1.0 | Language runtime (effects, optimized GC) |
| opam | >= 2.1 | Package manager |
| dune | >= 3.0 | Build system |
| librdkafka | >= 2.0 | Kafka client library (for connectors) |
| libssl | >= 1.1 | TLS for Async RPC |
| pkg-config | any | Build dependency resolution |
Installing the OCaml Toolchain
If you do not already have opam installed:
# Ubuntu/Debian
sudo apt-get install -y opam librdkafka-dev libssl-dev pkg-config
# macOS (Homebrew)
brew install opam librdkafka openssl pkg-config
# Initialize opam (first time only)
opam init --auto-setup
eval $(opam env)
# Create a switch with OCaml 5.3
opam switch create ripple 5.3.0
eval $(opam env)
Installing Ripple Dependencies
All OCaml dependencies are declared in ripple.opam and pinned to Jane Street v0.17 releases. Install them in one step:
cd ripple
opam install . --deps-only --yes
The full dependency list:
| Package | Version | Role |
|---|---|---|
core | >= 0.17.0 | Jane Street standard library replacement |
async | >= 0.17.0 | Cooperative concurrency (Deferred.t, RPC) |
bin_prot | >= 0.17.0 | Binary serialization (wire protocol) |
sexplib0 | >= 0.17.0 | S-expression serialization (schemas, checkpoints) |
ppx_jane | >= 0.17.0 | Meta-ppx including sexp, bin_io, compare, hash |
ppx_expect | >= 0.17.0 | Inline expect tests |
ppx_bench | >= 0.17.0 | Inline micro-benchmarks |
ppx_inline_test | >= 0.17.0 | Inline test runner |
core_bench | >= 0.17.0 | Benchmarking framework |
Building
# Full build
dune build
# Or equivalently:
make build
The build produces three binaries:
| Binary | Path | Purpose |
|---|---|---|
ripple-vwap-demo | bin/vwap_demo/main.exe | Demo pipeline |
ripple-worker | bin/worker/main.exe | Production worker process |
ripple-cli | bin/cli/main.exe | Command-line management tool |
Running Tests
# Run all inline expect tests
dune runtest
# Or:
make test
Every .ml file in lib/ contains inline %expect_test blocks. These are the primary test mechanism – there are no separate test files for unit tests. Integration tests live in test/.
Installing Git Hooks
Ripple ships a pre-commit hook that runs the benchmark suite and gates on regression:
make install-hooks
This installs hooks/pre-commit which runs dune runtest before allowing a commit. If any expect test fails, the commit is rejected.
Running Benchmarks
# Run the full OCaml benchmark suite (core_bench)
make bench
# This executes bench/run_benchmarks.ml which includes:
# B-01: Incremental stabilization throughput (1K and 10K symbols)
# B-02: bin_prot serialization roundtrip
# B-03: Delta diff performance
# B-05: Replay recovery (2K and 10K symbols)
# B-06: Schema validation and fingerprinting
Verifying the Installation
A quick smoke test to confirm everything works:
# Build, test, and benchmark in one command
make check
# Run the VWAP demo with synthetic data
make demo
The demo should produce CSV output to stdout and statistics to stderr, including throughput in events/sec and the final portfolio VWAP total.
Project Layout
ripple/
├── lib/
│ ├── kernel/ # Core types: Trade, Vwap, Effect_intf
│ ├── graph/ # Incremental graph engine, dirty_heap, cutoff
│ ├── schema/ # Schema, Delta, Compat
│ ├── wire/ # Envelope, Message, CRC-32C
│ ├── checkpoint/ # Checkpoint, Store (In_memory, Local_disk, S3)
│ ├── window/ # Window assigners, Watermark tracker
│ ├── observability/ # Metrics, Trace, Introspect, Alert
│ ├── coordinator/ # Hash ring, partition assignment
│ ├── worker/ # Worker lifecycle state machine
│ ├── connector/ # File source/sink, Kafka connector
│ ├── topology/ # Pipeline topology builder
│ └── ripple/ # Top-level Ripple module (facade)
├── bin/
│ ├── vwap_demo/ # VWAP demo binary
│ ├── worker/ # Worker binary
│ └── cli/ # CLI binary
├── bench/ # core_bench benchmarks
├── test/ # Integration and property tests
├── infra/ # Docker, Compose, Kubernetes manifests
└── book/ # This documentation (mdBook)