ROCm Library SONAME
Hello,
One thing that surprised me about the librocrand package was the version
number. The package is librocrand1 [1], which was not what I was
expecting. The existing rocrand package is described in the changelog as
"rocRAND-2.10.12 for ROCm 5.0.0" [2], and neither of those numbers have
the major version "1". After some research, I've come to believe that
the ROCm math libraries are not handling the VERSION [3] and SOVERSION
[4] properties correctly.
All of the ROCm math libraries now follow semantic versioning. Since
ROCm 4.3 they have been expected to provide full API and ABI
compatibility across minor and patch version bumps. The compatibility
commitment is akin to that provided by Qt. The only time when a breaking
change is allowed is on a major version bump. That is reflected in the
rocRAND version number 2.10.12. If there were a breaking change, the
major version would be incremented from 2 to 3. For other releases,
either the minor or the patch version number would be incremented. The
rocRAND library is functionally complete, so recently it has only been
incrementing the patch version number.
The rocRAND VERSION and SOVERSION properties have not been changed since
they were set to 1.1 in ROCm 2.7. I'm not particularly familiar with the
library VERSION or SOVERSION properties, but I suspect that is not the
correct way to use them. If I've understood correctly, they should be
incremented with each release.
I've read that it's a red flag when the SOVERSION matches the library
version, but as far as I can tell, that is common for libraries that
follow semantic versioning. For example, Qt5Core has a SONAME that
includes the major version number 5 and symlinks that match the library
version number.
My proposal for handling VERSION and SOVERSION moving forward is that
starting with ROCm 6.0, they would be set using the library version
number. For a library like rocBLAS (which will be making breaking
changes in ROCm 6.0), that would mean a progression like:
ROCm 5.4.0
Library Version: 2.46.0
VERSION: 0.1
SOVERSION: 0.1
SONAME: librocblas.so.0
ROCm 5.5.0
Library Version: 2.47.0
VERSION: 0.1
SOVERSION: 0.1
SONAME: librocblas.so.0
ROCm 6.0.0
Library Version: 3.0.0
VERSION: 3.0.0
SOVERSION: 3.0.0
SONAME: librocblas.so.3
ROCm 6.1.0
Library Version: 3.1.0
VERSION: 3.1.0
SOVERSION: 3.1.0
SONAME: librocblas.so.3
Strictly speaking, ROCm just needs to start incrementing the SOVERSION.
It doesn't have to be increased to match the VERSION. However, given
that semantic versioning will keep the two in sync, I'm thinking they
might as well skip ahead to make them match and keep things simple.
This is not my area of expertise, but given that Debian sets the package
name based on the SONAME, I suspect that you folks may have some
knowledge on the subject. If I'm totally wrong about this
VERSION/SOVERSION business, please let me know before I make an idiot
out myself.
Sincerely,
Cory Bloor
[1]:
https://salsa.debian.org/rocm-team/rocrand/-/blob/debian%2F5.0.0-2/debian/control#L23
[2]:
https://salsa.debian.org/rocm-team/rocrand/-/blob/debian%2F5.0.0-2/CHANGELOG.md#rocrand-21012-for-rocm-500
[2]: https://cmake.org/cmake/help/v3.25/prop_tgt/VERSION.html
[4]: https://cmake.org/cmake/help/v3.25/prop_tgt/SOVERSION.html
Reply to: