Development Guide

Topic: contributing.development

Setup and workflow for MathHook development.

Development Guide

Setup and workflow for MathHook development.

Prerequisites

• Rust 1.70+ (stable)
• Git
• Python 3.8+ with SymPy (for validation)

Quick Start

Clone and Build

git clone https://github.com/AhmedMashour/mathhook.git
cd mathhook
cargo build --release

Run Tests

# All tests (recommended)
gtimeout 600s cargo test --no-fail-fast

# Doctests only
gtimeout 600s cargo test --no-fail-fast --doc

# Specific crate
cargo test -p mathhook-core

Run Benchmarks

./scripts/bench.sh run       # Full benchmarks
./scripts/bench.sh quick     # Quick run
./scripts/bench.sh save pre  # Save baseline before changes
./scripts/bench.sh compare pre  # Compare after changes

Project Structure

mathhook/
├── crates/
│   ├── mathhook-core/       # Core mathematical engine
│   ├── mathhook-macros/     # Procedural macros (expr!, symbol!, etc.)
│   ├── mathhook/            # High-level user API
│   ├── mathhook-python/     # Python bindings (PyO3)
│   ├── mathhook-node/       # Node.js bindings (NAPI)
│   └── mathhook-benchmarks/ # Performance benchmarks
├── docs/                    # mdbook documentation
├── scripts/                 # Build and validation scripts
└── CLAUDE.md                # Development rules and standards

Crate Responsibilities

Development Workflow

Before Starting

git status                    # Check clean state
git checkout -b feature/name  # Create feature branch

Development Cycle

1. Read CONTRIBUTING.md - Understand rules and priorities
2. Plan the change - Consider mathematical correctness first
3. Implement - Use macros, follow style guide
4. Test - Run cargo test, add new tests
5. Validate - Run ./scripts/validate.sh for math operations
6. Format - Run cargo fmt
7. Lint - Run cargo clippy -- -D warnings

Before Committing

cargo fmt                      # Format code
cargo clippy -- -D warnings    # Zero warnings
cargo test                     # All tests pass

Key Commands

Documentation

mdbook

cd docs
mdbook serve --open  # Preview at localhost:3000
mdbook build         # Build static site

Rust Docs

cargo doc --open     # Generate and view API docs

Validation

SymPy Reference

Always verify mathematical operations against SymPy:

from sympy import *
x = Symbol('x')
print(simplify(sin(x)**2 + cos(x)**2))  # Should be 1

Validation Scripts

./scripts/validate.sh           # All validations
./scripts/validate.sh simplify  # Specific module
./scripts/validate.sh ode       # ODE solver

Performance

Benchmarking Workflow

# 1. Save baseline before changes
./scripts/bench.sh save before-change

# 2. Make your changes

# 3. Compare performance
./scripts/bench.sh compare before-change

Size Constraints

Common Issues

Parser Regeneration

# If grammar changes
lalrpop crates/mathhook-core/src/parser/grammar.lalrpop

Macro Not Found

Ensure mathhook-macros is in dependencies and macros are re-exported.

Test Timeout

Use gtimeout prefix for long-running tests:

gtimeout 600s cargo test --no-fail-fast

Getting Help

1. Read CONTRIBUTING.md - Contains all development rules
2. Check existing code - Follow established patterns
3. Run tests - They document expected behavior
4. Validate against SymPy - For mathematical correctness

Examples

API Reference

• Rust: ``
• Python: ``
• JavaScript: ``

See Also

• contributing.testing

• contributing.style

• contributing.documentation

• contributing.correctness

• contributing.architecture-reference