mirror of
https://github.com/clockworklabs/SpacetimeDB.git
synced 2026-03-20 09:01:05 +08:00
4c962b9170
# Description of Changes
This PR implements support for the `spacetime.json` configuration file
that can be used to set up common `generate` and `publish` targets. An
example of `spacetime.json` could look like this:
```
{
"dev_run": "pnpm dev",
"generate": [
{ "out-dir": "./foobar", "module-path": "region-module", "language": "c-sharp" },
{ "out-dir": "./global", "module-path": "global-module", "language": "c-sharp" },
],
"publish": {
"database": "bitcraft",
"module-path": "spacetimedb",
"server": "local",
"children": [
{ "database": "region-1", "module-path": "region-module", server: "local" },
{ "database": "region-2", "module-path": "region-module", server: "local" }
]
}
}
```
With this config, running `spacetime generate` without any arguments
would generate bindings for two targets: `region-module` and
`global-module`. `spacetime publish` without any arguments would publish
three modules, starting from the parent: `bitcraft`, `region-1`, and
`region-2`. On top of that, the command `pnpm dev` would be executed
when using `spacetime dev`.
It is also possible to pass additional command line arguments when
calling the `publish` and `generate` commands, but there are certain
limitations. There is a special case when passing either a module path
to generate or a module name to publish. Doing that will filter out
entries in the config file that do not match. For example, running:
```
spacetime generate --project-path global-module
```
would only generate bindings for the second entry in the `generate`
list.
In a similar fashion, running:
```
spacetime publish region-1
```
would only publish the child database with the name `region-1`
Passing other existing arguments is also possible, but not all of the
arguments are available for multiple configs. For example, when running
`spacetime publish --server maincloud`, the publish command would be
applied to all of the modules listed in the config file, but the
`server` value from the command line arguments would take precedence.
Running with arguments like `--bin-path` would, however, would throw an
error as `--bin-path` makes sense only in a context of a specific
module, thus this wouldn't work: `spacetime publish --bin-path
spacetimedb/target/debug/bitcraft.wasm`. I will throw an error unless
there is only one entry to process, thus `spacetime publish --bin-path
spacetimedb/target/debug/bitcraft.wasm bitcraft` would work, as it
filters the publish targets to one entry.
# API and ABI breaking changes
None
# Expected complexity level and risk
3
The config file in itself is not overly complex, but when coupled with
the CLI it is somewhat tricky to get right. There are also some changes
that I had to make to how clap arguments are validated - because the
values can now come from both the config file and the clap config, we
can't use some of the built-in validations like `required`, or at least
I haven't found a clean way to do so.
# Testing
I've added some automated tests, but more tests and manual testing is
coming.
---------
Signed-off-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Co-authored-by: bradleyshep <148254416+bradleyshep@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: = <cloutiertyler@gmail.com>
Co-authored-by: Tyler Cloutier <cloutiertyler@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 . --module-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.