Hi Cory, Cordell Bloor, on 2022-11-20: > 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. The library SOVERSION is there to reflect the semantic of symbol introduction and removal in the library. If symbols are added, the minor number must be incremented, and if symbols are removed or functions change meaning (API breakage), then the major number must be incremented. I lack the history to tell for sure, but if the SOVERSION has not been bumped since then, that means: * either no symbols move in the library since ROCm 2.7, * or symbols changes have been overlooked. On the distribution side, the little symbol tracking we do is to detect ABI breakages. When a function disappears or changes interface, it is not possible to replace the shared library in- place on a running system without rebuilding its reverse dependencies; this is important when proceeding to major system upgrades: on rolling releases, and from one release to the next. In Debian, introduction of a breakage in reverse dependencies require coordinating a transition with the release team[5]. When SOVERSION tracking is done on your upstream side, then as downstream consumers, I think we're happy to stick to whichever versionning sounds sensible, as long as it is strictly monotonic and the major version bump matches breaking changes. :) > 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. It depends, if the library version matches the SOVERSION, and not the other way around, then it could be justified I guess. Red flag would be if the library follows a regular version bump schedules, and the SOVERSION follows but mismatches the semantic of symbols changes. Unnecessary bumps would trigger unnecessary package renames (which in Debian context means additional round trips through NEW manual review), and missing bumps would cause reverse dependencies breakages. > 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 I'm not sure if that would make things easier for you as upstream, but what might be interesting would be to bump to the library version only on next ABI or ABI plus API change. Downstream, that would avoid us unnecessary round trips through ftp and release teams consecutive to package name change and the triggered transition. On the other hand I can understand a major ROCm version bump will be a good opportunity to refresh these. I agree aligning the library version to the SOVERSION will make things less confusing on the long run. For now, Debian AI ROCm packages are tracking ROCm version for the practical reason that the tags and release pages expose resources which are versioned with the ROCm version[7]. I note the library version is visible on the release page, but the link points to an archive which is defined using a tag matching a ROCm version[8]. I think it could be useful to be able to track the library version instead for the package version. The reason is that currently I try to keep at least hipcc components consistent and align versions, but maybe I'm triggering unnecessary uploads and rebuilds if the underlying library hasn't changed beyond the ROCm version number. Note if actually implementing this that it may be necessary on the Debian side to carry on with 5.0.0+really2.46.0 version numbers until the library version crosses the ROCm version at the time of the change in version number (this is necessary to keep version numbers strictly monotonic). > 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. There are no stupid questions, this topic is far from being trivial and it took me quite some time to put back the pieces of the puzzle for myself when trying to answer. I hope I didn't, but I wouldn't be surprised if I missed a couple of points. Thanks for having taken the time to wrap that up, and tried to investigate possible ways forward! > 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 [5]: https://wiki.debian.org/Teams/ReleaseTeam/Transitions [6]: https://www.debian.org/doc/debian-policy/ch-sharedlibs.html [7]: https://github.com/ROCmSoftwarePlatform/rocRAND/releases [8]: https://github.com/ROCmSoftwarePlatform/rocRAND/archive/refs/tags/rocm-5.3.3.zip Have a nice day, :) -- Étienne Mollier <emollier@emlwks999.eu> Fingerprint: 8f91 b227 c7d6 f2b1 948c 8236 793c f67e 8f0d 11da Sent from /dev/pts/3, please excuse my verbosity.
Attachment:
signature.asc
Description: PGP signature