Repository navigation
feat(ffi): the shared library's name carries the major version - #171
Merged
Merged
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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, withlibemberwave_ffi.soor.dylibas 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 incrates/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 SONAMElibemberwave_ffi.so.MAJOR, the install name@rpath/libemberwave_ffi.MAJOR.dylibwith compatibility versionMAJOR.0.0and the crate's version as the current one.scripts/package_ffi.sh: fills a release archive'slibdirectory (the versioned file, the unversioned link, with--with-staticthe static library) and checks the library's own name withreadelforotool..github/workflows/release.ymlandscripts/check_c_example.shuse 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.cp -a), ARCHITECTURE, CONTRIBUTING, D75, the README's 1.0 checklist.Testing
On macOS:
cargo test -p emberwave-ffi --test exports(both tests),otool -lshows@rpath/libemberwave_ffi.0.dylib, compatibility 0.0.0, current 0.18.1, andscripts/check_c_example.shbuilds and runs the C examples againstlibemberwave_ffi.0.dylib(otool -Lof the program shows it) with every vector at the same PSNR. On Linux in a container: the same test,readelf -dshowslibemberwave_ffi.so.0,scripts/package_ffi.shmakes the file and the link. A reviewer agent read the change.