Drop the append-only versioning doctrine; document the version script

Module APIs and the library's exported ABI are versioned and retired
deliberately: a break ships as a new table version or a new symbol
version node, and consumers judge the versions they are handed.

Document src/libdpm-core.map — what it pins, what belongs in it, and
how a generation is retired — and declare DPM_CORE_0.1 as the shape
the next retired node takes.
This commit is contained in:
2026-08-14 02:35:03 -04:00
parent 298f4d5afe
commit 267529bee3
7 changed files with 164 additions and 118 deletions

View File

@@ -1,3 +1,28 @@
/*
* libdpm-core.map — the linker version script for libdpm-core.so
*
* Passed to the linker with --version-script. It does two things: it
* pins the library's exported symbol list, and it stamps every exported
* symbol with the version node named below.
*
* What goes in `global`: every function declared in the public header,
* include/dpm/core.h, and nothing else. The library compiles with
* hidden default visibility, so `local: *` is what the implementation
* already gets; listing it here makes the export set explicit and fails
* the link loudly if the two ever disagree.
*
* Changing it: adding a public function means adding its name here in
* the same commit that adds it to the header. Removing or renaming one
* breaks every consumer already linked against it, so a removal ships
* as a new node above the existing one — binaries already linked
* against the older node keep resolving it while new links bind to the
* newer one.
*
* The node name carries the ABI generation. Newest node first, retired
* generations below it. DPM_CORE_0.1 at the bottom was never released —
* it is there so the next break follows its shape instead of inventing
* one.
*/
DPM_CORE_1.0 {
global:
dpm_open;
@@ -17,3 +42,6 @@ DPM_CORE_1.0 {
local:
*;
};
DPM_CORE_0.1 {
};