Repository map¶
d-SEAMS is seven repositories. This one, seams-core, holds the engine and everything that has to change with it. Each language binding is a separate repository that builds against a seams-core tag and releases with the same version number.
What lives where¶
Repository |
Holds |
Publishes |
|---|---|---|
The C++ engine ( |
The |
|
The Python binding: |
|
|
The Lua and Fennel binding, |
LuaRocks |
|
The R package |
The R source package |
|
The Julia packages |
The Julia General registry, through |
|
The crates |
crates.io |
|
The Fortran modules |
The fpm package |
A change belongs in seams-core when it touches a classifier, a reader, the
neighbour list, seams.h, seams_lang.h, the CLI, or an engine driver. A
change that only wraps an existing C entry point for one language belongs in
that language’s repository. A new analysis lands here first, with a C entry
point, a C test and a page under docs/api/c.md; the bindings then wrap it
after they move their pin.
How a binding pins seams-core¶
Every binding names one seams-core revision, builds libseams and
libseams_lang from it (or from a release package), and runs its own suite
against that build. A release pins the tag; between releases the pin can be a
commit on a release branch.
Binding |
Where the pin lives |
What its CI builds |
|---|---|---|
PydSEAMSlib |
|
The wheel, with the engine as a Meson subproject |
yodaStruct |
|
The Lua module, with the engine as a Meson subproject |
dseams-r |
|
The bundled source package, and a linked check against seams-core built at the pin |
Dseams.jl |
|
seams-core at the pin, then |
dseams-rs |
|
seams-core at the pin, then |
dseams-fortran |
|
seams-core at the pin, installed, then |
The binding’s own version is the seams-core version it binds:
pydseamslib==2.14.0 calls the 2.14.0 engine. This repository’s tests do
not build any binding. The C ABI tests (meson test seams_lang_fixtures seams_lang_frames) are the contract the bindings rely on. The core docs
run their Python snippets against the installed pydseamslib of the same
version, which the Docs workflow installs from the matching PydSEAMSlib tag.
Release order¶
seams-core: the
vX.Y.Ztag, the GitHub release, condalibseamsfromrecipe/, and the Yggdrasil pull request forlibseams_jllfrompackaging/yggdrasil. Release has the steps.PydSEAMSlib, dseams-rs, yodaStruct, dseams-fortran and dseams-r, in any order: each moves its pin to
vX.Y.Z, sets its version toX.Y.Z, and follows its own release document.Dseams.jl, after
libseams_jllX.Y.Zis merged in Yggdrasil and registered.
The core Docs workflow installs pydseamslib from the PydSEAMSlib vX.Y.Z
tag, so the published core docs follow step 2 for Python.
Develop seams-core and a binding together¶
Build seams-core from a checkout, then point the binding at that build instead of at its pin.
git clone https://github.com/d-SEAMS/seams-core.git
cd seams-core
pixi run setup
pixi run build
bbdir/src holds libseams.so, libyodaLib.so and the generated
seams_version.h, bbdir/bindings holds libseams_lang.so, and
include/ and bindings/cxx/ hold the other headers.
bbdir/meson-uninstalled has a pkg-config file for each of seams,
seams-core and seams-lang that names those directories. With
PKG_CONFIG_PATH there, pkg-config resolves the three packages to the
build tree and the source headers:
export PKG_CONFIG_PATH=$PWD/bbdir/meson-uninstalled
cc consumer.c $(pkg-config --cflags --libs seams-lang) \
-Wl,-rpath,$PWD/bbdir/bindings -Wl,-rpath,$PWD/bbdir/src
The libraries find each other and the patched chemfiles in
bbdir/chemfiles-prefix/lib through their own rpath. The consumer only
needs a runpath, or LD_LIBRARY_PATH, for the directories pkg-config
names with -L. meson test seams_lang_pkgconfig builds a consumer this
way and against an install. For each binding:
PydSEAMSlib and yodaStruct: replace
subprojects/seams-corewith a symlink to the checkout (Meson uses an existing subproject directory before the wrap), then rebuild.dseams-r: set
DSEAMS_ROOTto the checkout;configurecopies the engine from there instead of downloading the pin. WithSEAMS_LIBDIRandSEAMS_INCLUDEset it links the builtlibseams_langinstead.Dseams.jl: set
SEAMS_LANG_LIBtobbdir/bindings/libseams_lang.soandSEAMS_LIBtobbdir/src/libseams.so, runjulia --project=. dev/develop_jll.jl, thenPkg.test.dseams-rs: set
SEAMS_LIB_DIRtobbdir/srcand runcargo test.dseams-fortran: set
FPM_LDFLAGSto-L$SC/src -L$SC/bindings -Wl,-rpath,$SC/src -Wl,-rpath,$SC/bindingswithSCatbbdir, then runfpm test; itslang_taskstest linkslibseams_lang. Its Meson build finds both libraries withPKG_CONFIG_PATH=$SC/meson-uninstalled.
When the binding needs a seams-core change, land it here first, then move the binding’s pin to the commit that carries it.