boxddd-sys

Low-level Rust FFI for the vendored Box3D C API.

Most users should depend on boxddd instead. Use boxddd-sys directly when you need raw C symbols, custom native linking, or binding-generation maintenance.

Direct FFI use bypasses boxddd's owned-definition lowering, opaque handle provenance, owner-before-FFI authorization, world ledger and transaction finalizers, lifetime guards, callback/task protocols, and Result-first typed errors. A caller that chooses this layer owns all native aliasing, synchronization, callback, and destruction invariants and must not mutate native objects that are simultaneously owned by a live safe wrapper.

Build Contract

Default builds compile the vendored Box3D C sources with the Rust cc crate and link the resulting static library into boxddd-sys.

Normal users need a platform C compiler, such as MSVC Build Tools on Windows, Clang on macOS, or GCC/Clang on Linux. Normal users do not need CMake, LLVM, libclang, or bindgen because checked-in pregenerated bindings are used by default.

The vendored source, exact upstream commit, declarative local patches, generated bindings, browser provider v2 ABI, and artifact fingerprints are declared in box3d-upstream.toml. Build and provider tooling consume the generated Rust contract derived from that manifest rather than maintaining independent source, patch, or ABI version strings.

Features

• build-from-source: compile vendored Box3D C sources. Enabled by default.
• bindgen: allow regenerating bindings when BOXDDD_SYS_FORCE_BINDGEN=1 is set.
• double-precision: build Box3D with BOX3D_DOUBLE_PRECISION and use matching pregenerated bindings.
• disable-simd: define BOX3D_DISABLE_SIMD.
• validate: define BOX3D_VALIDATE.

Native Linking

Disable default features to skip vendored C compilation and link an external box3d library:

boxddd-sys = { version = "0.3", default-features = false }

Optional environment variables:

• BOXDDD_SYS_LINK_LIB: external library name. Defaults to box3d.
• BOXDDD_SYS_LINK_SEARCH: native library search directory.

Upstream And Binding Maintenance

Pregenerated bindings are ABI-mode specific. The default build uses bindings_pregenerated.rs; double-precision uses bindings_pregenerated_double.rs.

Regenerate both checked-in binding modes only when maintaining this crate:

python tools/update_box3d_and_bindings.py generate --mode both

Given a local clone that contains the manifest's exact upstream commit object, verify the vendored subset, declared patches, generated sample and capability inventories, Rust contract, and both binding modes without rewriting checked-in artifacts:

python tools/update_box3d_and_bindings.py check --source repo-ref/box3d --mode both

This check proves source and patch provenance, generated-artifact reproducibility, ABI-mode agreement, and provider capability classification. It does not prove the semantic safety of APIs built above the raw bindings; that is the responsibility of boxddd's ownership, provenance, lifetime, callback, and typed-error tests.

The direct forced-bindgen checks remain useful diagnostics:

BOXDDD_SYS_FORCE_BINDGEN=1 cargo check -p boxddd-sys --features bindgen
BOXDDD_SYS_FORCE_BINDGEN=1 cargo check -p boxddd-sys --features "bindgen double-precision"

See Upstream Conformance for the source synchronization contract, read-only check semantics, patch workflow, and upgrade procedure.

WASM

WASM support uses a manifest-driven provider v2 contract with an explicitly classified capability subset.

The v2 provider exports boxddd_provider_abi_revision; Node and browser loaders must match that sentinel to the manifest's bridge revision before instantiating the Rust application. This catches a stale provider even if it is accidentally published under the current asset name.

Provider mode currently supports only the default single-precision ABI. Combining BOXDDD_SYS_WASM_MODE=provider with double-precision is rejected at build time. Native and WASI source builds continue to support the double-precision feature.

Useful environment variables:

• BOXDDD_SYS_WASM_MODE: compile-only, source, or provider.
• WASI_SYSROOT: WASI libc sysroot for wasm32-wasip1 source builds.
• WASI_SDK_PATH: WASI SDK root. Used as $WASI_SDK_PATH/share/wasi-sysroot when WASI_SYSROOT is unset.

Detailed WASM commands live in the workspace documentation: https://github.com/Latias94/boxddd/blob/main/docs/platforms/wasm.md.

Check-Only Builds

BOXDDD_SYS_SKIP_CC=1 skips native C compilation for check-only workflows. Do not use it for normal runnable native builds.

BOXDDD_SYS_SKIP_CC=1 cargo check -p boxddd-sys

License

This crate is licensed as MIT OR Apache-2.0. Vendored Box3D is MIT-licensed.