Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add soversion to shared library #23

Merged
merged 3 commits into from
May 22, 2024
Merged

Conversation

mgates3
Copy link
Collaborator

@mgates3 mgates3 commented May 22, 2024

TestSweeper (and related libraries, BLAS++, LAPACK++, SLATE) have used a date version scheme: yyyy-mm-dd. (At one point, dd was simply a counter starting from 0, but now it is the month day.) This has certain advantages, for instance making it clear when someone is using an out-dated version. However, it doesn't work well for versioning the ABI (application binary interface), which works better with semantic versioning, interpreted as applied to the ABI. The semantic versioning spec is for the API (application programming interface), which can change differently than the ABI. For instance:

  • Reordering members of a struct changes the ABI but not the API. Client code needs recompiling but does not need modifications.
  • Removing a function changes both the API and the ABI. Client code needs to be updated.
  • Changing a templated function's prototype changes the API, but not necessarily the ABI if it is not instantiated in the library. Similarly, changing a macro changes the API but not the ABI.

The GNU libtool manual explicitly says, "Never try to set the interface numbers so that they correspond to the release number of your package."

Therefore, we are versioning the ABI separately from the API, using a form of semantic versioning. We will use the abi-compliance-checker to compare releases of the library. Rules:

  • If a public struct is modified or removed, or arguments of a function change (e.g., int to int64), or a function is removed, bump the major version and reset the minor and micro version.
  • If a new public structure or function is added, bump the minor version and reset the micro version.
  • If changes are only bug fixes or internal structures and functions, bump the micro version.

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