synapse-db

Development Environment Setup

Quick reference for setting up your Synapse DB development environment.

One-Line Setup

./scripts/setup.sh

This automated script handles everything you need to start developing.

What Gets Installed

1. Rust Toolchain

2. Development Tools

3. Git Hooks

4. Project Build

Manual Installation

If the automated script fails or you prefer manual setup:

Step 1: Install Rust

Linux/macOS:

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

Windows: Download from rustup.rs

Step 2: Install Tools

# Essential tools
cargo install mdbook git-cliff cargo-audit

# Optional but recommended
cargo install cargo-watch

Step 3: Setup Git Hooks

./scripts/install-hooks.sh

Step 4: Build Project

# Build and test
cargo build
cargo test

# Build documentation
mdbook build
cargo doc --no-deps --all-features

Verifying Installation

Check that everything is installed correctly:

# Rust toolchain
rustc --version
cargo --version

# Development tools
mdbook --version
git-cliff --version
cargo audit --version
cargo watch --version

# Build status
cargo build
cargo test

System Requirements

Minimum Requirements

Rust Version

Troubleshooting

Rust not found after installation

Add Cargo to your PATH:

# Bash/Zsh
echo 'source $HOME/.cargo/env' >> ~/.bashrc
source ~/.bashrc

# Fish
echo 'source $HOME/.cargo/env.fish' >> ~/.config/fish/config.fish

Build errors

Update Rust and clean build:

rustup update stable
cargo clean
cargo build

Hook installation fails

Manually copy hooks:

cp hooks/pre-commit .git/hooks/
cp hooks/commit-msg .git/hooks/
cp hooks/prepare-commit-msg .git/hooks/
chmod +x .git/hooks/*

mdBook not found

Ensure ~/.cargo/bin is in your PATH:

export PATH="$HOME/.cargo/bin:$PATH"

Permission denied on Linux/macOS

Make scripts executable:

chmod +x scripts/*.sh
chmod +x hooks/*

Post-Setup

After setup completes, you can:

Start Development

# Run the application
cargo run

# Auto-rebuild on changes
cargo watch -x run

# Run tests continuously
cargo watch -x test

View Documentation

# Serve with live reload
mdbook serve
# Open http://localhost:3000

# Open API docs
cargo doc --open

Before Committing

# Run all checks
./scripts/pre-push-check.sh

# Or manually
cargo fmt
cargo clippy
cargo test

Development Workflow

  1. Create a branch 
    git checkout -b feature/my-feature
  2. Make changes
    • Code auto-formats on commit
    • Commit messages validated automatically
  3. Run checks 
    ./scripts/pre-push-check.sh
  4. Push changes 
    git push origin feature/my-feature
  5. Create Pull Request
    • CI runs automatically
    • All checks must pass

Development Tools Usage

Code Quality

cargo fmt              # Format code
cargo clippy           # Lint code
cargo test             # Run tests
cargo check            # Quick compile check

Documentation

mdbook serve           # User guide (live reload)
mdbook build           # Build user guide
cargo doc --open       # API documentation
./scripts/generate-changelog.sh  # Update changelog

Performance

cargo build --release  # Optimized build
cargo bench            # Run benchmarks (if configured)

Security

cargo audit            # Security vulnerabilities
cargo outdated         # Outdated dependencies

Environment Variables

The setup script respects these environment variables:

Uninstalling

To remove Synapse DB development environment:

# Remove Rust (if desired)
rustup self uninstall

# Remove development tools
cargo uninstall mdbook git-cliff cargo-audit cargo-watch

# Remove repository
cd ..
rm -rf synapse-db

Getting Help

Next Steps

After setup:

  1. Read CONTRIBUTING.md - Contribution guidelines
  2. Check book/README.md - Documentation guide
  3. Review DOCUMENTATION.md - Documentation system
  4. Explore examples/ - Example code
  5. Join discussions on GitHub

Setup Time: ~10-15 minutes depending on internet speed

Questions? Open an issue or discussion on GitHub!

This site is open source. Improve this page.