Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Development

The engine, the C API, and the C++ oracle live in seams-core. This repository is the Rust side: the safe crate, the generated declarations, the build script, this book, and the examples. A new analysis or a new C function lands in seams-core first. It is wrapped here after SEAMS_CORE_REF in seams-core.env moves to a commit that contains it.

Contributor conventions for this repository are in AGENTS.md at the repository root. The engine book is docs.dseams.info.

Build and test

Build seams-core at the pinned commit with tests enabled, then run the checks from the repository root. The workflow file .github/workflows/ci.yml is the same sequence.

. ./seams-core.env
git clone "$SEAMS_CORE_REPO" ../seams-core
git -C ../seams-core checkout "$SEAMS_CORE_REF"
(cd ../seams-core && pixi run meson setup bbdir -Dwith_tests=true -Dwith_cli=false \
 && pixi run ninja -C bbdir src/libseams.so bindings/binding_oracle)

export SEAMS_LIBDIR=$PWD/../seams-core/bbdir/src
export SEAMS_INCLUDE=$PWD/../seams-core/include:$SEAMS_LIBDIR
export SEAMS_CPP_ORACLE=$PWD/../seams-core/bbdir/bindings/binding_oracle
export SEAMS_SOURCE_ROOT=$PWD/../seams-core
export OMP_NUM_THREADS=1

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test -- --test-threads=1
cargo test --examples -- --test-threads=1
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps

dseams/tests/ice.rs calls every safe wrapper on the cubic cell. dseams/tests/cpp_match.rs compares those analyses with the C++ oracle on ice Ih, sI, an XYZ file, a CON file, and the triclinic sH dump. It skips, and says so, when SEAMS_CPP_ORACLE or SEAMS_SOURCE_ROOT is unset. dseams/examples/ holds ice, minimal, ice_ih, lang_tasks, and binding_overhead. cargo test --examples checks their output.

Unset SEAMS_LIBDIR and set PKG_CONFIG_PATH=$PWD/../seams-core/bbdir/meson-uninstalled to test the pkg-config path against the same tree.

The bundled feature, from a filled dseams-sys/vendor/:

python3 dseams-sys/vendor.py --source ../seams-core
cargo clippy --features bundled --all-targets -- -D warnings
cargo test --features bundled --test ice --examples -- --test-threads=1
cargo +1.85.0 build --features bundled --all-targets

1.85.0 is the minimum supported compiler (rust-version in the workspace manifest).

Declarations

dseams-sys/src/lib.rs is generated. Regenerate it when seams.h changes, and do not edit it by hand:

python3 dseams-sys/gen_sys.py ../seams-core/include/seams.h dseams-sys/src/lib.rs

CI diffs that file against the generator output for the pinned header. dseams-sys/sources.txt lists the translation units the bundled feature compiles, relative to seams-core. Update it when the link closure of src/seams_api.cpp changes.

Documentation

This book is the user-facing documentation:

mdbook build docs

mdBook 0.5.4 is the version CI installs. The API reference is rustdoc, as the API page describes. After cargo doc --no-deps --workspace, the coverage check fails if a public symbol is missing from the HTML:

DOCS_RS=1 cargo doc --no-deps --workspace
python3 docs/check_rustdoc.py target/doc
python3 docs/check_book.py docs/book

check_rustdoc.py parses dseams/src/lib.rs and dseams-sys/src/lib.rs. Hiding a public item from rustdoc fails that check. check_book.py checks the built HTML: internal links, the tutorial recordings, and the engine-book links.

Changelog

User-visible changes add a fragment under changelog.d/. The names and the types are in changelog.d/README.md. Commits use Conventional Commits.

The release order, from the seams-core tag through cargo publish and the tag on this repository, is in AGENTS.md.