Development Setup

This page covers how to set up a local development environment for the laurus-ruby binding, build it, and run the test suite.

Prerequisites

• Rust 1.85 or later with Cargo
• Ruby 3.1 or later with Bundler
• Repository cloned locally

git clone https://github.com/mosuka/laurus.git
cd laurus

Build

Development build

Compiles the Rust native extension in debug mode. Re-run after any Rust source change.

cd laurus-ruby
bundle install
bundle exec rake compile

Release build

gem build laurus.gemspec

Verify the build

ruby -e "
require 'laurus'
index = Laurus::Index.new
puts index.stats
"
# {"document_count"=>0, "vector_fields"=>{}}

Testing

Tests use Minitest and are located in test/.

# Run all tests
bundle exec rake test

To run a specific test file:

bundle exec ruby -Ilib -Itest test/test_index.rb

Linting and formatting

# Rust lint (Clippy)
cargo clippy -p laurus-ruby -- -D warnings

# Rust formatting
cargo fmt -p laurus-ruby --check

# Apply formatting
cargo fmt -p laurus-ruby

Cleaning up

# Remove build artifacts
bundle exec rake clean

# Remove installed gems
rm -rf vendor/bundle

Project layout

laurus-ruby/
├── Cargo.toml          # Rust crate manifest
├── laurus.gemspec      # Gem specification
├── Gemfile             # Bundler dependency file
├── Rakefile            # Rake tasks (compile, test, clean)
├── lib/
│   └── laurus.rb       # Ruby entrypoint (loads native extension)
├── ext/
│   └── laurus_ruby/    # Native extension build configuration
│       └── extconf.rb  # rb_sys extension configuration
├── src/                # Rust source (Magnus binding)
│   ├── lib.rs          # Module registration
│   ├── index.rs        # Index class
│   ├── schema.rs       # Schema class
│   ├── query.rs        # Query classes
│   ├── search.rs       # SearchRequest / SearchResult / Fusion
│   ├── analysis.rs     # Tokenizer / Filter / Token
│   ├── convert.rs      # Ruby ↔ DataValue conversion
│   └── errors.rs       # Error mapping
├── test/               # Minitest tests
│   ├── test_helper.rb
│   └── test_index.rb
└── examples/           # Runnable Ruby examples