mirror of
https://github.com/clockworklabs/SpacetimeDB.git
synced 2026-05-12 02:37:53 -04:00
Jason Larabie
52b6c66fa1
# Description of Changes This adds C++ server bindings (/crate/bindings-cpp) to allow writing C++ 20 modules. - Emscripten WASM build system integration with CMake - Macro-based code generation (SPACETIMEDB_TABLE, SPACETIMEDB_REDUCER, etc) - All SpacetimeDB types supported (primitives, Timestamp, Identity, Uuid, etc) - Product types via SPACETIMEDB_STRUCT - Sum types via SPACETIMEDB_ENUM - Constraints marked with FIELD* macros # API and ABI breaking changes None # Expected complexity level and risk 2 - Doesn't heavily impact any other areas but is complex macro C++ structure to support a similar developer experience, did have a small impact on init command # Testing - [x] modules/module-test-cpp - heavily tested every reducer - [x] modules/benchmarks-cpp - tested through the standalone (~6x faster than C#, ~6x slower than Rust) - [x] modules/sdk-test-cpp - [x] modules/sdk-test-procedure-cpp - [x] modules/sdk-test-view-cpp - [x] Wrote several test modules myself - [x] Quickstart smoketest [Currently in progress] - [ ] Write Blackholio C++ server module --------- Signed-off-by: Jason Larabie <jason@clockworklabs.io> Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com> Co-authored-by: Ryan <r.ekhoff@clockworklabs.io> Co-authored-by: John Detter <4099508+jdetter@users.noreply.github.com>
SpacetimeDB SDK Client Comparison Tool
Compares client code generated from Rust and C++ bindings modules to validate type system equivalence and catch regressions.
Quick Start
./run_client_comparison.sh
This builds the C++ module, regenerates clients, and runs both client and module schema comparisons.
How It Works
3-Step Process:
- Build & Regenerate: Compiles
lib.cppand generates fresh C++ client - Compare: Runs client code and module schema comparisons in parallel
- Summarize: Shows statistics and generates detailed analysis files
Prerequisites:
- SpacetimeDB CLI:
cargo build --release -p spacetimedb-cli
Output:
client_diff_analysis.txt- Detailed client code differencesmodule_diff_analysis.txt- Module schema comparison- Console summaries with key metrics
Scripts
run_client_comparison.sh (Main)
Complete workflow: build → regenerate → compare → summarize
scripts/compare_clients.sh
Client code comparison with intelligent filtering:
- Ignores paths, version comments, whitespace
- Shows only meaningful code differences
- Provides accurate file statistics
scripts/compare_modules.sh
Module schema comparison:
- Publishes WASM to temporary databases
- Extracts schemas via
spacetime describe --json - Compares typespace, tables, reducers, named types
scripts/regenerate_cpp_client.sh
Rebuilds C++ client only (no comparison)
Understanding Results
Client Comparison:
- File counts: Total files generated by each SDK
- Identical files: Files with no meaningful differences (after filtering)
- Difference types: Type representations, imports, structure flattening
Module Schema:
- Typespace: Core type definitions and relationships
- Common differences: Registration order, duplicates, special type handling
Usage
Standard workflow:
cd crates/bindings-cpp/tests/client-comparison
./run_client_comparison.sh
Update baselines:
# Rust baseline
cd rust-sdk-test
spacetime generate --lang rust --out-dir . --project-path ../../../modules/sdk-test
# Rust baseline
./scripts/regenerate_rust_client.sh
# C++ baseline
./scripts/regenerate_cpp_client.sh
Troubleshooting
- "CLI not found": Build CLI with
cargo build --release -p spacetimedb-cli - "Client generation failed": Check if lib.cpp publishes successfully
- "No differences": Normal if no changes were made
The tool validates C++ bindings functionality by comparing generated client code and module schemas against the Rust SDK baseline.