Development Setup Guide

This guide will help you set up a development environment for ApexStore.

💻 System Requirements

Minimum Requirements

  • OS: Linux, macOS, or Windows (with WSL2 recommended)
  • RAM: 4GB (8GB+ recommended for large workloads)
  • Disk: 2GB free space
  • CPU: Any modern CPU (multi-core recommended for testing)
  • OS: Ubuntu 22.04 LTS or macOS 13+
  • RAM: 16GB
  • Disk: 10GB free space (SSD preferred)
  • CPU: 4+ cores

🛠️ Installing Prerequisites

1. Rust Toolchain

Installation

# Install Rust using rustup (recommended)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Follow the prompts, then reload your shell
source $HOME/.cargo/env

Verify Installation

# Check Rust version (should be 1.70+)
rustc --version
# Output: rustc 1.75.0 (or higher)

# Check Cargo version
cargo --version
# Output: cargo 1.75.0 (or higher)

Additional Components

# Install Clippy (linter)
rustup component add clippy

# Install rustfmt (formatter)
rustup component add rustfmt

# Install rust-src (for IDE support)
rustup component add rust-src

2. Git

Linux (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install git

macOS

# Using Homebrew
brew install git

# Or install Xcode Command Line Tools
xcode-select --install

Windows

Download from git-scm.com

Verify Installation

git --version
# Output: git version 2.x.x

Install VS Code

  • Download from code.visualstudio.com
  • Or use package manager: 
    # Ubuntu/Debian
sudo snap install code --classic

# macOS
brew install --cask visual-studio-code

Install Extensions

Essential:

  1. rust-analyzer - Rust language support

    • ID: rust-lang.rust-analyzer
    • Features: Auto-completion, go-to-definition, inline errors

  2. CodeLLDB (optional) - Debugging support

    • ID: vadimcn.vscode-lldb

Recommended: 3. Better TOML - TOML syntax highlighting

  • ID: bungcip.better-toml

  1. Error Lens - Inline error highlighting

    • ID: usernamehw.errorlens

  2. crates - Cargo.toml dependency management

    • ID: serayuzgur.crates

VS Code Settings

Create .vscode/settings.json in project root:

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

📦 Project Setup

1. Clone the Repository

# Clone your fork
git clone https://github.com/YOUR_USERNAME/ApexStore.git
cd ApexStore

# Add upstream remote
git remote add upstream https://github.com/ElioNeto/ApexStore.git

# Verify remotes
git remote -v

2. Build the Project

# Debug build (faster compilation)
cargo build

# Release build (optimized)
cargo build --release

# Build with API feature
cargo build --release --features api

First build may take 5-10 minutes as Cargo downloads and compiles dependencies.

3. Run Tests

# Run all tests
cargo test

# Run tests with output
cargo test -- --nocapture

# Run specific test
cargo test test_memtable_insert

4. Configuration

# Copy environment template
cp .env.example .env

# Edit configuration (optional)
nano .env

Example Development Configuration (.env):

# Server
HOST=127.0.0.1
PORT=8080

# LSM Engine
DATA_DIR=.lsm_data_dev
MEMTABLE_MAX_SIZE=2097152  # 2MB for faster flushing in dev
BLOCK_CACHE_SIZE_MB=32

# Logging
RUST_LOG=debug
ENABLE_METRICS=true

🧪 Development Workflow

Running the CLI

# Debug mode
cargo run

# Release mode (faster)
cargo run --release

Available REPL Commands:

> help                 # Show available commands
> put key value        # Insert or update key
> get key              # Retrieve value
> delete key           # Delete key (tombstone)
> stats                # Show statistics
> exit                 # Exit REPL

Running the API Server

# Debug mode
cargo run --features api --bin apexstore-server

# Release mode
cargo run --release --features api --bin apexstore-server

# With custom port
PORT=3000 cargo run --release --features api --bin apexstore-server

Testing the API:

# Insert a key
curl -X POST http://localhost:8080/keys \
  -H "Content-Type: application/json" \
  -d '{"key": "user:1", "value": "Alice"}'

# Get a key
curl http://localhost:8080/keys/user:1

# Get statistics
curl http://localhost:8080/stats/all

Code Quality Checks

# Format code
cargo fmt

# Check formatting (CI mode)
cargo fmt -- --check

# Run Clippy linter
cargo clippy

# Clippy with strict mode (CI mode)
cargo clippy -- -D warnings

# Check for unused dependencies
cargo machete  # Requires: cargo install cargo-machete

Running Benchmarks

# Install criterion
cargo install cargo-criterion

# Run all benchmarks
cargo bench

# Run specific benchmark
cargo bench memtable_insert

# Generate HTML report
open target/criterion/report/index.html

🐳 Docker Development

Build Docker Image

# Build production image
docker build -t apexstore:dev .

# Run in development mode with volume mount
docker run -d \
  --name apexstore-dev \
  -p 8080:8080 \
  -v $(pwd)/data:/data \
  -v $(pwd)/.env:/app/.env \
  apexstore:dev

Docker Compose Development

# Start services
docker-compose up -d

# View logs
docker-compose logs -f apexstore

# Restart after code changes
docker-compose restart

# Stop services
docker-compose down

🛠️ Debugging

Using LLDB (VS Code)

  1. Install CodeLLDB extension
  2. Create .vscode/launch.json:
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "lldb",
      "request": "launch",
      "name": "Debug CLI",
      "cargo": {
        "args": ["build", "--bin=apexstore"]
      },
      "args": [],
      "cwd": "${workspaceFolder}"
    },
    {
      "type": "lldb",
      "request": "launch",
      "name": "Debug Server",
      "cargo": {
        "args": ["build", "--features", "api", "--bin=apexstore-server"]
      },
      "args": [],
      "cwd": "${workspaceFolder}"
    },
    {
      "type": "lldb",
      "request": "launch",
      "name": "Debug Test",
      "cargo": {
        "args": ["test", "--no-run", "--lib"]
      },
      "args": ["test_memtable_insert"],
      "cwd": "${workspaceFolder}"
    }
  ]
}
  1. Set breakpoints in code
  2. Press F5 to start debugging

Using println! Debugging

#![allow(unused)]
fn main() {
// In your code
pub fn put(&mut self, key: &[u8], value: &str) -> Result<()> {
    println!("[DEBUG] Inserting key: {:?}", String::from_utf8_lossy(key));
    self.wal.append(key, value)?;
    println!("[DEBUG] WAL append successful");
    self.memtable.insert(key, value);
    Ok(())
}
}

Run with:

cargo run -- 2>&1 | grep DEBUG

Using RUST_LOG

# Set log level
export RUST_LOG=debug

# Or inline
RUST_LOG=trace cargo run

# Filter by module
RUST_LOG=apexstore::core::engine=debug cargo run

📈 Performance Profiling

CPU Profiling (Linux)

# Install flamegraph
cargo install flamegraph

# Generate flamegraph
sudo cargo flamegraph --bin apexstore-server

# Open flamegraph.svg in browser
firefox flamegraph.svg

Memory Profiling

# Using valgrind (Linux)
valgrind --leak-check=full --track-origins=yes \
  ./target/debug/apexstore

# Using heaptrack (Linux)
heaptrack ./target/debug/apexstore
heaptrack_gui heaptrack.apexstore.*.gz

Benchmark Profiling

# Profile specific benchmark
cargo bench --bench memtable_bench -- --profile-time=10

# With flamegraph
cargo flamegraph --bench memtable_bench

🧰 Testing

Unit Tests

# Run all unit tests
cargo test --lib

# Run tests in specific module
cargo test --lib core::memtable

# Run single test
cargo test test_memtable_insert

Integration Tests

# Run all integration tests
cargo test --test '*'

# Run specific integration test file
cargo test --test recovery_test

Test Coverage

# Install tarpaulin (Linux only)
cargo install cargo-tarpaulin

# Generate coverage report
cargo tarpaulin --out Html

# Open report
firefox tarpaulin-report.html

Stress Testing

# Create stress test script
cat > stress_test.sh << 'EOF'
#!/bin/bash
for i in {1..10000}; do
  curl -X POST http://localhost:8080/keys \
    -H "Content-Type: application/json" \
    -d "{\"key\": \"key_$i\", \"value\": \"value_$i\"}" &
done
wait
EOF

chmod +x stress_test.sh

# Run stress test
./stress_test.sh

📚 Documentation

Generating Documentation

# Generate and open docs
cargo doc --open

# Include private items
cargo doc --document-private-items --open

# Generate for all features
cargo doc --all-features --open

Writing Documentation

All public APIs should have documentation:

#![allow(unused)]
fn main() {
/// Brief description (appears in summary).
///
/// Longer description with more details.
///
/// # Arguments
///
/// * `key` - Description of key parameter
/// * `value` - Description of value parameter
///
/// # Returns
///
/// Description of return value
///
/// # Errors
///
/// Description of possible errors
///
/// # Examples
///
/// ```
/// let engine = LsmEngine::new(config)?;
/// engine.put(b"key", "value")?;
/// ```
///
/// # Panics
///
/// Description of panic conditions (if any)
///
/// # Safety
///
/// Description of safety requirements (for unsafe functions)
pub fn put(&mut self, key: &[u8], value: &str) -> Result<()> {
    // Implementation
}
}

🐞 Troubleshooting

Common Issues

Issue: Compilation Errors After Update

# Clean build artifacts
cargo clean

# Update dependencies
cargo update

# Rebuild
cargo build

Issue: Tests Failing Randomly

# Run tests serially (not in parallel)
cargo test -- --test-threads=1

Issue: Port Already in Use

# Find process using port 8080
lsof -i :8080  # macOS/Linux

# Kill process
kill -9 <PID>

# Or use different port
PORT=3000 cargo run --features api --bin apexstore-server

Issue: Out of Disk Space

# Clean target directory (safe, can be rebuilt)
rm -rf target/

# Clean cargo cache
cargo cache --autoclean

Issue: Slow Compilation

# Use faster linker (Linux)
sudo apt-get install lld
export RUSTFLAGS="-C link-arg=-fuse-ld=lld"

# Or use mold (even faster)
cargo install mold
export RUSTFLAGS="-C link-arg=-fuse-ld=mold"

# Enable incremental compilation (in Cargo.toml)
[profile.dev]
incremental = true

🚀 Next Steps

  1. ✅ Read CONTRIBUTING.md for contribution guidelines
  2. ✅ Explore the codebase structure
  3. ✅ Pick an issue to work on
  4. ✅ Join discussions on GitHub

💬 Getting Help

Happy Coding! 🦀

Last updated: March 2026