Development Guide¶

Prerequisites¶

Rust: 1.70+ (install from rustup.rs)
Python: 3.11+ with pip
Maturin: pip install maturin
Optional: Graphviz for visualization (brew install graphviz on macOS)

Building from Source¶

# Clone repository
git clone https://github.com/tarekziade/rustnn.git
cd rustnn

# See all available commands
make help

# Build Rust library
make build

# Build Python package (downloads ONNX Runtime automatically)
make python-dev

# Run tests
make test                     # Rust tests
make python-test              # Python tests (includes WPT conformance)

# Build documentation
make docs-serve               # Live preview at http://127.0.0.1:8000
make docs-build               # Build static site

Running Examples¶

Python Examples¶

# Install package first
make python-dev

# Run examples
make python-example           # Run all examples
make mobilenet-demo           # MobileNetV2 on all 3 backends
make text-gen-demo            # Text generation with attention
make text-gen-train           # Train model on sample data
make text-gen-trained         # Generate with trained weights

# Or run individual examples
python examples/python_simple.py
python examples/python_matmul.py
python examples/mobilenetv2_complete.py examples/images/test.jpg --backend cpu

Rust Examples¶

# Validate a graph
make run

# Generate visualization
make viz

# Convert to ONNX
make onnx

# Convert to CoreML
make coreml

Testing¶

Python Tests¶

# All tests (includes WPT conformance tests)
make python-test

# WPT conformance tests only
make python-test-wpt

# Or use pytest directly
python -m pytest tests/ -v

# Specific test
python -m pytest tests/test_python_api.py::test_context_creation -v

# With coverage
python -m pytest tests/ --cov=webnn --cov-report=html

Rust Tests¶

# All Rust tests
make test

# Or use cargo directly
cargo test

# Specific module
cargo test validator

# With output
cargo test -- --nocapture

Feature Flags¶

The project uses Cargo feature flags to control optional functionality. The Makefile handles these automatically:

# Python bindings with ONNX Runtime (recommended)
make python-dev              # Includes python,onnx-runtime features

# Build Python wheel
make python-build            # Production build with all features

# Or use cargo/maturin directly if needed
cargo build --features python,onnx-runtime
maturin develop --features python,onnx-runtime,coreml-runtime

Development Workflow¶

1. Make Changes¶

Edit Rust code in src/ or Python code in python/webnn/.

2. Format Code¶

# Rust (automatically formats)
make fmt

# Python
black python/ tests/

3. Run Tests¶

# Full test suite
make test                    # Rust tests
make python-test             # Python tests

# Or run comprehensive validation
make validate-all-env        # Build, test, convert, validate

4. Check Code Coverage¶

# Generate coverage report
make coverage                # Text output
make coverage-html           # HTML report
make coverage-open           # HTML report + open in browser

# For CI/CD
make coverage-lcov           # LCOV format for upload to coverage services

See Code Coverage Guide for detailed coverage analysis and best practices.

5. Build and Test Python Package¶

make python-dev              # Install in development mode
make python-test             # Run all tests

6. Update Documentation¶

Edit files in docs/ and preview:

make docs-serve              # Live preview at http://127.0.0.1:8000
make docs-build              # Build static site
make ci-docs                 # Build in strict mode (CI)

Debugging¶

Rust¶

# Debug build
make build

# Run with visualization
make viz

# Run with backtrace
RUST_BACKTRACE=1 make run

Python¶

# Run specific example with verbose output
python examples/python_simple.py

# Or enable debug logging in code
import webnn
import logging

logging.basicConfig(level=logging.DEBUG)

# Your code here

Common Tasks¶

Add a New Operation¶

Update graph.rs with new operation type
Add validation logic in validator.rs
Implement conversion in converters/onnx.rs and converters/coreml.rs
Add Python binding in src/python/graph_builder.rs
Add tests in tests/test_python_api.py

Add a New Backend¶

Create new file in src/executors/your_backend.rs
Add feature flag in Cargo.toml
Implement executor trait/functions
Add conditional compilation in src/executors/mod.rs
Wire up in src/python/context.rs backend selection
Add tests

Update Documentation¶

Edit markdown files in docs/
Preview with make docs-serve
Check links and formatting
Build with make docs-build
Test in strict mode with make ci-docs

Troubleshooting¶

Maturin Build Fails¶

# Update Rust
rustup update

# Clean all build artifacts
make clean-all

# Rebuild from scratch
make python-dev

Import Errors¶

# Ensure you're in the right virtual environment
which python

# Clean and reinstall
make python-clean
make python-dev

# Verify installation
python -c "import webnn; print(webnn.__version__)"

ONNX Runtime Issues¶

The Makefile automatically downloads ONNX Runtime for you:

# Download ONNX Runtime manually if needed
make onnxruntime-download

# Or install system-wide (optional)
brew install onnxruntime

# Build with system ONNX Runtime
export ORT_STRATEGY=system
export ORT_LIB_LOCATION=/opt/homebrew/lib
make python-dev

Test Failures¶

# Run tests with verbose output
make python-test

# Run specific test
python -m pytest tests/test_python_api.py::test_name -xvs

# Check if backend is available
python -c "import webnn; ctx = webnn.ML().create_context(); print(ctx.accelerated)"

Code Style¶

Rust¶

Follow Rust API Guidelines
Use cargo fmt for formatting
Use cargo clippy for linting
Write doc comments for public APIs

Python¶

Follow PEP 8
Use type hints
Write docstrings for public APIs
Use black for formatting

Git Workflow¶

Commits¶

# Stage changes
git add .

# Commit with descriptive message
git commit -m "Add feature X

- Detail 1
- Detail 2

[BOT] Generated with [Claude Code](https://claude.com/claude-code)"

# Push
git push origin main

Pre-commit Hooks¶

The project uses pre-commit hooks to ensure code quality:

cargo fmt --check and cargo clippy automatically run when Rust files change
make python-ty-check runs Ty against pywebnn when Python files change
Tests run automatically in CI

CI/CD¶

GitHub Actions¶

The project uses GitHub Actions for CI:

.github/workflows/ci.yml - Main CI pipeline
Runs on push and pull requests
Tests on Linux and macOS
Builds Python wheels
Runs all tests

Local CI Simulation¶

# Run the same checks as CI
make fmt                     # Format code
cargo clippy -- -D warnings  # Lint checks
make validate-all-env        # Full validation pipeline
make ci-docs                 # Documentation build (strict mode)

Development Guide¶

Prerequisites¶

Building from Source¶

Running Examples¶

Python Examples¶

Rust Examples¶

Testing¶

Python Tests¶

Rust Tests¶

Feature Flags¶

Development Workflow¶

1. Make Changes¶

2. Format Code¶

3. Run Tests¶

4. Check Code Coverage¶

5. Build and Test Python Package¶

6. Update Documentation¶

Debugging¶

Rust¶

Python¶

Common Tasks¶

Add a New Operation¶

Add a New Backend¶

Update Documentation¶

Troubleshooting¶

Maturin Build Fails¶

Import Errors¶

ONNX Runtime Issues¶

Test Failures¶

Code Style¶

Rust¶

Python¶

Git Workflow¶

Commits¶

Pre-commit Hooks¶

CI/CD¶

GitHub Actions¶

Local CI Simulation¶

Resources¶