============== 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 ---------------- .. table:: +-----------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | Repository | Holds | Publishes | +=======================================================================+===================================================================================================================================================================================================================================================================================================================================================================================================================+======================================================================================================================================+ | `d-SEAMS/seams-core `_ | The C++ engine (``libyodaLib``), the C API ``libseams`` (``include/seams.h``), the C ABI ``libseams_lang`` (``bindings/cxx/seams_lang.h``), the ``seams`` command, the engine drivers (``engines/``, ``adapters/python`` ``dseams_insitu``), the C and C++ documentation, the science scripts, the videos, the conda recipe (``recipe/``) and the Yggdrasil recipe for ``libseams_jll`` (``packaging/yggdrasil``) | The ``vX.Y.Z`` tag, the GitHub release, conda ``libseams``, ``libseams_jll``, `https://docs.dseams.info `_ | +-----------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | `d-SEAMS/PydSEAMSlib `_ | The Python binding: ``import dseams`` (array calls) and ``import pydseams`` (the Frame API), with their tests and docs | ``pydseamslib`` on PyPI | +-----------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | `d-SEAMS/yodaStruct `_ | The Lua and Fennel binding, ``require("dseams")`` | LuaRocks ``dseams`` | +-----------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | `d-SEAMS/dseams-r `_ | The R package ``dseams`` | The R source package | +-----------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | `d-SEAMS/Dseams.jl `_ | The Julia packages ``Dseams`` (over ``libseams_lang``) and ``Seams`` (over ``libseams``) | The Julia General registry, through ``libseams_jll`` | +-----------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | `d-SEAMS/dseams-rs `_ | The crates ``dseams-sys`` (raw FFI over ``seams.h``) and ``dseams`` (safe wrapper) | crates.io | +-----------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | `d-SEAMS/dseams-fortran `_ | The Fortran modules ``seams_c`` and ``seams`` | The fpm package ``dseams`` | +-----------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ 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. .. table:: +----------------+-------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ | Binding | Where the pin lives | What its CI builds | +================+=======================================================================================================+====================================================================================+ | PydSEAMSlib | ``subprojects/seams-core.wrap`` (``revision``) | The wheel, with the engine as a Meson subproject | +----------------+-------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ | yodaStruct | ``subprojects/seams-core.wrap`` (``revision``) | The Lua module, with the engine as a Meson subproject | +----------------+-------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ | dseams-r | ``tools/seams-core.ref`` (``SEAMS_CORE_REPO``, ``SEAMS_CORE_REF``) | The bundled source package, and a linked check against seams-core built at the pin | +----------------+-------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ | Dseams.jl | ``SEAMS_CORE_REPO`` and ``SEAMS_CORE_REF`` in ``.github/workflows/CI.yml`` | seams-core at the pin, then ``Pkg.test`` for ``Dseams`` and ``Seams`` | +----------------+-------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ | dseams-rs | ``seams-core.env`` (``SEAMS_CORE_REPO``, ``SEAMS_CORE_REF``), read by CI and ``dseams-sys/vendor.py`` | seams-core at the pin, then ``cargo test`` | +----------------+-------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ | dseams-fortran | ``SEAMS_CORE_REPOSITORY`` and ``SEAMS_CORE_REF`` in ``.github/workflows/ci.yml`` | seams-core at the pin, installed, then ``fpm test`` | +----------------+-------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ 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 ------------- 1. seams-core: the ``vX.Y.Z`` tag, the GitHub release, conda ``libseams`` from ``recipe/``, and the Yggdrasil pull request for ``libseams_jll`` from ``packaging/yggdrasil``. `Release `_ has the steps. 2. PydSEAMSlib, dseams-rs, yodaStruct, dseams-fortran and dseams-r, in any order: each moves its pin to ``vX.Y.Z``, sets its version to ``X.Y.Z``, and follows its own release document. 3. Dseams.jl, after ``libseams_jll`` ``X.Y.Z`` is 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. .. code:: bash 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: .. code:: bash 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-core`` with a symlink to the checkout (Meson uses an existing subproject directory before the wrap), then rebuild. - dseams-r: set ``DSEAMS_ROOT`` to the checkout; ``configure`` copies the engine from there instead of downloading the pin. With ``SEAMS_LIBDIR`` and ``SEAMS_INCLUDE`` set it links the built ``libseams_lang`` instead. - Dseams.jl: set ``SEAMS_LANG_LIB`` to ``bbdir/bindings/libseams_lang.so`` and ``SEAMS_LIB`` to ``bbdir/src/libseams.so``, run ``julia --project=. dev/develop_jll.jl``, then ``Pkg.test``. - dseams-rs: set ``SEAMS_LIB_DIR`` to ``bbdir/src`` and run ``cargo test``. - dseams-fortran: set ``FPM_LDFLAGS`` to ``-L$SC/src -L$SC/bindings -Wl,-rpath,$SC/src -Wl,-rpath,$SC/bindings`` with ``SC`` at ``bbdir``, then run ``fpm test``; its ``lang_tasks`` test links ``libseams_lang``. Its Meson build finds both libraries with ``PKG_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.