Bump the ABI numbers¶
This page lists the steps to change the C ABI stamp of rgpot-core and the C++
soversion and layout stamp of librgpot.
Each step names the constant to change and the check that fails when it is
stale.
What each number means and its history are in
ABI stamps.
The C ABI stamp¶
The numbers live in rgpot-core/src/version.rs as
RGPOT_ABI_VERSION_MAJOR, RGPOT_ABI_VERSION_MINOR and
RGPOT_ABI_LAYOUT_REVISION.
abi_major: increment for a change a caller built against the old header cannot survive: removing or renaming an exported function, changing a signature, changing the meaning of an existing argument or status code. Resetabi_minorto 0.abi_minor: increment for an additive change that leaves every old call valid: a new exported function, a new status code, a new enum value a caller may ignore.layout_revision: increment when the size or field order of an exported struct changes, or an existing field changes type, even when every function keeps its name.
Then:
Regenerate the header with
pixi run gen-headerand commit it with the change.Append each new exported function to
scripts/abi_core_baseline.txt. The list only grows; it holds the functions of a build with the crate’s default features.Run the crate tests with
pixi run rust-test.committed_header_matches_the_cratefails when the version and ABI macros, or the Hessian-vector declarations, of the committed header differ from the crate.the_abi_baseline_is_declared_by_the_headerfails when the header stops declaring a baseline name.
In a Meson build with with_rust_core on Linux, the test abi_core_symbols
fails when librgpot_core.so no longer exports a baseline name.
scripts/abi_baseline.txt and scripts/abi_baseline_fast.txt are the same
check for the neighbour-list and fast-list exports of librgpot (Meson test
abi_symbols).
The neighbour-list C ABI has its own number, RGPOT_NLIST_ABI in
CppCore/rgpot/nlist/rgpot_nlist.h.
The C++ soversion and layout stamp¶
The constants live in CppCore/rgpot/abi/CxxLayout.hpp.
kCxxSoversion is the ELF soversion of librgpot; CppCore/meson.build and
CMakeLists.txt read it, so it is written nowhere else.
A change to the size, alignment or a field offset of a covered type moves the hash by itself. Bump
kCxxSoversionin the same change, update the platform table as described below, and append a line toCppCore/rgpot/abi/cxx_soversion_ledger.txtwith the new soversion and the fingerprint thatCppCore/tests/check_cxx_soversion.pyprints. Do not edit a shipped ledger line.kCxxLayoutRevision: increment when a change keeps every size and offset and still alters the ABI: reordering virtual functions without changing their count, changing the meaning of a field, or changing a base class of a covered type. The revision is an input of the hash, so bumpkCxxSoversionin that change as well.kPotentialBaseVirtuals,kPotentialBaseCacheVirtualsandkPotentialVirtualscount the virtual functions ofPotentialBase(without and withRGPOT_HAS_CACHE) and the onesPotential<Derived>adds.CppCore/tests/check_virtual_counts.pycounts thevirtualdeclarations inPotential.hppand fails when a count is stale. Update the constant and incrementkCxxLayoutRevisiontogether.To cover a new type, add it to
detail::compute_hash()and bumpkCxxSoversionin the same commit; the hash changes, so no revision bump is needed.
CppCore/tests/check_cxx_soversion.py (Meson test CxxSoversion) fails when:
the last ledger soversion differs from
kCxxSoversion, or the ledger soversions do not increase;the fingerprint of the stamp’s inputs (the text of
compute_hash(), the four constants, the covered structures and the data members of the covered classes) differs from the last ledger line;compared with
main, a shipped ledger line changed or was dropped, orcompute_hash()changed without a new ledger line;the SONAME of the built
librgpotis notlibrgpot.so.NforN=kCxxSoversion;the table tags and the
RGPOT_CXX_PLATFORM_LISTED_TAGguards differ;the live no-cache hash of a platform that has a table row differs from that row.
A platform without a row passes the last check, and CxxLayout.cc prints a
compiler message that the tag is unlisted.
Updating the platform table¶
kCxxSoversionTable holds one no-cache hash per platform tag, copied from CI.
Do not copy a hash from another platform or from a local build.
The stamp printer
CppCore/tests/print_cxx_layout_stamp.cc prints one line: RGPOT_CXX_LAYOUT_STAMP tag…
hash=…
hashdec=… features=… revision=…=. features is 1 for a cache build; ignore those lines. The workflow “C++ layout stamp” (.github/workflows/cxx-layout-stamp.yml) runs the printer on Linux x8664,
Linux aarch64, macOS arm64, macOS x8664and Windows MSVC.
The Linux and macOS wheel builds run it too, from the compiler that builds the
wheel, and so does the Meson test CxxSoversion.
The wheels skip musllinux, so no CI log prints a linux-musl tag.
When the soversion is bumped:
Increment
kCxxSoversion.Empty
kCxxSoversionTableand delete the listed-platform guards, so every platform builds and the printers run.Read each
RGPOT_CXX_LAYOUT_STAMPline whosefeaturesis 0.Add one table row per distinct tag, using that line’s
hashas0x<hash>ull. Add a matching guard: an#if, then#elif, onRGPOT_OS_*,RGPOT_ARCH_*,RGPOT_STDLIB_*andRGPOT_MODEL_*, which definesRGPOT_CXX_PLATFORM_LISTEDas 1 andRGPOT_CXX_PLATFORM_LISTED_TAGas that tag.Append one ledger line: the new soversion and the fingerprint the check prints.
Push and wait until the jobs that printed the hashes are green.
CxxLayout.ccfails to compile on a listed platform whose live hash differs from its row.
CxxLayoutTest loads the fixture CppCore/tests/layout_fixture.cc, a shared
object built with a ForceOut that has an extra field, and requires that its
hash differs and that its compatibility check refuses the real stamp.
kCxxSoversion applies to librgpot only.
librgpot_mpi keeps soversion 3 in both build systems, and check_cxx_soversion.py
fails when that changes.