Skip to content

feat(ffi): the shared library's name carries the major version - #171

Merged
with-developer merged 5 commits into
mainfrom
feat/versioned-library-name
Nov 19, 2026
Merged

with-developer merged 5 commits into
mainfrom
feat/versioned-library-name

Conversation

@with-developer

Copy link
Copy Markdown
Owner

What changes for a client of the shared library, and how to revert

A program linked against the library from this version on records libemberwave_ffi.so.0 (Linux) or @rpath/libemberwave_ffi.0.dylib (macOS) and needs that file at run time; the release archives hold it, with libemberwave_ffi.so or .dylib as a link to it, so a program linked before, which asks for the unversioned name, still finds its file. The number is the crate's major version, 0 now and 1 from 1.0.0, so that from 1.0 it means the ABI (D69). Windows is unchanged (emberwave_ffi.dll); the static library and the XCFramework are not affected. To revert, set the names back in crates/emberwave-ffi/build.rs.

Purpose

Decision 1 of D75 (issue #165, left by the maintainer to their agent): a version in the shared library's name, before 1.0.

Changes

  • crates/emberwave-ffi/build.rs: the SONAME libemberwave_ffi.so.MAJOR, the install name @rpath/libemberwave_ffi.MAJOR.dylib with compatibility version MAJOR.0.0 and the crate's version as the current one.
  • scripts/package_ffi.sh: fills a release archive's lib directory (the versioned file, the unversioned link, with --with-static the static library) and checks the library's own name with readelf or otool. .github/workflows/release.yml and scripts/check_c_example.sh use it, so the C example job, which runs on Linux, macOS and Windows on every PR, tests the archive layout before a tag.
  • crates/emberwave-ffi/tests/exports.rs: a test reads the SONAME or the install name and the versions and compares them with the crate's.
  • Docs: the FFI README (files, the link, which file to ship, cp -a), ARCHITECTURE, CONTRIBUTING, D75, the README's 1.0 checklist.

Testing

On macOS: cargo test -p emberwave-ffi --test exports (both tests), otool -l shows @rpath/libemberwave_ffi.0.dylib, compatibility 0.0.0, current 0.18.1, and scripts/check_c_example.sh builds and runs the C examples against libemberwave_ffi.0.dylib (otool -L of the program shows it) with every vector at the same PSNR. On Linux in a container: the same test, readelf -d shows libemberwave_ffi.so.0, scripts/package_ffi.sh makes the file and the link. A reviewer agent read the change.

From 1.0 the number in a shared library's name should mean its ABI, so that
a program linked against one major version never loads another (D69, D75).
The library names itself by the crate's major version, 0 now and 1 from
1.0.0: the SONAME libemberwave_ffi.so.0 on Linux, the install name
@rpath/libemberwave_ffi.0.dylib on macOS with a compatibility version of 0.0.0
and the crate's version as its current one. Windows keeps emberwave_ffi.dll.

Cargo still makes libemberwave_ffi.so and .dylib. scripts/package_ffi.sh
copies the file to its versioned name, leaves the unversioned one as a link,
adds the static library for a release, and checks the library's own name
with readelf or otool. The release workflow and scripts/check_c_example.sh
use it, so that the C example job tests the layout of the archives on every
OS before a tag, and the C examples run from the versioned name. A test next
to the export test reads the SONAME or the install name and the versions
and compares them with the crate's.

For a client: a program linked from this version on records the versioned
name and needs that file at run time, which the archives hold; a program
linked before asks for the unversioned name, which they keep as a link.

Claude-Session: https://claude.ai/code/session_019fJGoCTvP5e7n599q3ZQ42
…and the README

D75 says what was done for decision 1 and what a client of the library sees;
ARCHITECTURE's note on the library's name, CONTRIBUTING's release step and
the README's 1.0 checklist follow.

Claude-Session: https://claude.ai/code/session_019fJGoCTvP5e7n599q3ZQ42
…checks

A review of the versioned library name found that the README's own recipe for
the C example built against cargo's output directory, which has no file under
the name the program now records, so the program could not start. The recipe,
the CMake file's comment and its default directory now use the packaged
directory, as scripts/check_c_example.sh does.

readelf's labels are translated, so its SONAME line is read with LC_ALL=C in
the script and in the test. scripts/package_ffi.sh now reads the library's own
name before it copies anything, so a library built before a change of version
fails without leaving a misnamed file behind; it accepts only the exact
--with-static, says that relative paths are the repository's, and the README
no longer makes a stray `lib` directory at the root. The README's sentence on
what a program never loads says Linux and macOS and from this change on, and
which file to ship; CONTRIBUTING tells the 1.0.0 release to change the names
the README gives.

Claude-Session: https://claude.ai/code/session_019fJGoCTvP5e7n599q3ZQ42
@with-developer
with-developer merged commit 0b0840b into main Nov 19, 2026
7 checks passed
@with-developer
with-developer deleted the feat/versioned-library-name branch November 19, 2026 09:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant