Skip to content

CLAUDE.md

Latest commit

 

History

History
98 lines (74 loc) · 3.77 KB

CLAUDE.md

File metadata and controls

98 lines (74 loc) · 3.77 KB
Raw

CLAUDE.md

Project Overview

Safe Rust bindings for Ceres Solver, a C++ library for solving large-scale non-linear least squares (NLLS) optimization problems. The project is a Cargo workspace with three crates:

  • ceres-solver: Safe Rust bindings (main crate, src/)
  • ceres-solver-sys: Unsafe FFI bindings via the cxx crate (ceres-solver-sys/)
  • ceres-solver-src: Builds and statically links bundled Ceres Solver from source (ceres-solver-src/)

MSRV: 1.85.0 (Rust 2024 edition)

Build and Test Commands

# Build with bundled Ceres (preferred for development)
cargo build --features source

# Build with system-installed Ceres
cargo build

# Check all targets
cargo check --all-targets --workspace --features source

# Test with bundled source
cargo test --features source

# Test with system Ceres
cargo test --features system

# Format code
cargo fmt --all

# Lint (no warnings allowed)
cargo clippy --all-targets --workspace --no-default-features --features source -- -Dwarnings

# Run all pre-commit checks
pre-commit run --all-files

Project Structure

src/                    # Main crate (safe Rust API)
│   lib.rs              # Library entry point with top-level examples
│   nlls_problem.rs     # Core: NllsProblem builder
│   curve_fit.rs        # 1-D curve fitting convenience wrapper
│   solver.rs           # SolverOptions / SolverSummary
│   cost.rs             # CostFunction type definitions
│   loss.rs             # Loss functions (Huber, Cauchy, Tukey, …)
│   parameter_block.rs  # ParameterBlock with bounds management
│   residual_block.rs   # ResidualBlock ID types
│   error.rs            # Error types (thiserror)
│   types.rs            # Shared helper types
ceres-solver-sys/src/
│   lib.rs              # Rust FFI declarations (cxx)
│   lib.cpp             # C++ bridge implementation
│   lib.h               # C++ header
ceres-solver-src/       # CMake-based static library builder
.github/workflows/test.yml  # CI (Ubuntu + macOS, MSRV + stable)

Code Conventions

  • Standard Rust naming: snake_case for functions/variables, PascalCase for types
  • Builder pattern throughout (e.g., ResidualBlockBuilder, SolverOptionsBuilder)
  • Consuming methods — builders take self and return a new/modified type
  • Error types use thiserror; all error enums live in src/error.rs
  • Doc comments: //! for module-level, /// for items; include examples where useful
  • Minimize new dependencies; for MSRV compatibility, versions of cxx/cxx-build may be pinned

Adding New Features

  1. Check the feature exists in the supported Ceres Solver C++ API (2.2)
  2. If adding FFI:
    • Update ceres-solver-sys/src/lib.h and lib.cpp (C++ bridge)
    • Update ceres-solver-sys/src/lib.rs (Rust cxx declarations)
  3. Add safe Rust wrappers in the appropriate src/ file
  4. Write tests (unit tests in the same file; integration tests under tests/)
  5. Use the approx crate for floating-point comparisons in tests
  6. Update the feature status checklist in README.md if applicable
  7. Add an entry to CHANGELOG.md (Keep a Changelog format, semantic versioning)

CI

GitHub Actions runs on Ubuntu and macOS against MSRV (1.85) and stable Rust:

  • cargo-fmt — formatting check
  • cargo-clippy — lint check (-Dwarnings)
  • ceres-built-from-source — tests with --features source
  • system-ceres — tests with system-installed Ceres

Windows support is limited/experimental and not part of CI.

FFI Safety Notes

  • All unsafe FFI code is isolated in ceres-solver-sys; ceres-solver must remain safe
  • Parameter blocks use pin semantics to ensure stable memory addresses across the FFI boundary
  • Use modern C++17 features through cxx; avoid raw pointer arithmetic in new code