Development Setup¶

Set up your development environment for contributing to Polymathy.

Prerequisites¶

Rust 1.70+ (stable)
Git
Docker (optional, for running dependencies)

Install Rust¶

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Clone and Build¶

# Clone the repository
git clone https://github.com/skelfresearch/polymathy.git
cd polymathy

# Build the project
cargo build

# Run tests
cargo test

Development Environment¶

Environment Variables¶

Copy the sample environment file:

cp sample.env .env

Edit .env with your local settings:

SEARXNG_URL=http://localhost:8888/search
PROCESSOR_URL=http://localhost:8081/v1/process
SERVER_HOST=127.0.0.1
SERVER_PORT=8080
RUST_LOG=debug

Running Locally¶

# Development mode with debug output
RUST_LOG=debug cargo run

# Release mode
cargo run --release

Setting Up Dependencies¶

Option 1: Docker Compose¶

Create a docker-compose.dev.yml:

version: '3.8'

services:
  searxng:
    image: searxng/searxng:latest
    ports:
      - "8888:8080"
    volumes:
      - ./dev/searxng:/etc/searxng

Start dependencies:

docker-compose -f docker-compose.dev.yml up -d

Option 2: Manual Setup¶

Follow the SearxNG installation guide to set up a local instance.

Development Workflow¶

1. Create a Branch¶

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-number-description

2. Make Changes¶

Edit code, following our code style guide.

3. Test Your Changes¶

# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run with output
cargo test -- --nocapture

4. Format and Lint¶

# Format code
cargo fmt

# Run linter
cargo clippy -- -D warnings

5. Build Documentation¶

# Rust documentation
cargo doc --open

# MkDocs (from documentation/ directory)
cd documentation
pip install mkdocs-material
mkdocs serve

6. Commit Changes¶

git add .
git commit -m "feat: add new feature"
# or
git commit -m "fix: resolve issue #123"

Follow Conventional Commits.

IDE Setup¶

VS Code¶

Recommended extensions:

rust-analyzer - Rust language support
Even Better TOML - TOML file support
crates - Dependency version checking

Settings (.vscode/settings.json):

{
    "rust-analyzer.checkOnSave.command": "clippy",
    "editor.formatOnSave": true,
    "[rust]": {
        "editor.defaultFormatter": "rust-lang.rust-analyzer"
    }
}

IntelliJ IDEA / CLion¶

Install the Rust plugin for full IDE support.

Useful Commands¶

Command	Description
`cargo build`	Build the project
`cargo run`	Run the binary
`cargo test`	Run tests
`cargo fmt`	Format code
`cargo clippy`	Run linter
`cargo doc --open`	Generate and view docs
`cargo update`	Update dependencies
`cargo tree`	Show dependency tree

Debugging¶

Enable Debug Logging¶

RUST_LOG=polymathy=debug cargo run

Specific Module Logging¶

RUST_LOG=polymathy::api=debug,polymathy::search=trace cargo run

Troubleshooting¶

Build Errors¶

# Clean and rebuild
cargo clean
cargo build

Dependency Issues¶

# Update Cargo.lock
cargo update

Test Failures¶

# Run with backtrace
RUST_BACKTRACE=1 cargo test