mk: add .so name versioning, resolves #32

[sreimers]

@robert-scheck Can you check if soname handling fits your needs/requirements?

@alfredh I saw that you added and reverted a similar change some time ago: creytiv/re@1d19127

Are there any problems I should be aware of or i should test?

[alfredh]

after building this branch I get:

$ objdump -p libre.so | grep 'SONAME'
  SONAME               libre.so.11

is it correct that the number after so should be 11 ?

[sreimers]

is it correct that the number after so should be 11 ?

Yes it's currently VER_ABI := $(VER_MAJOR)$(VER_MINOR), but we can start by libre.so.0 and count ABI different.

My thought was a new Feature release, increments ABI too. but we can also specify a stricter ABI compatibility
and setup some tests.

[alfredh]

I am not sure about this PR.

I guess @robert-scheck should test and review it.

I sometimes look at the Opus project for inspiration. Here is similar info
for libopus from Debian 10:

$ dpkg -l | grep libopus0
ii  libopus0:amd64                         1.3-1                               amd64        Opus codec runtime library
ii  libopus0:i386                          1.3-1                               i386         Opus codec runtime library

$ l /usr/lib/x86_64-linux-gnu/libopus.*
-rw-r--r-- 1 root root 701100 Dec 17  2018 /usr/lib/x86_64-linux-gnu/libopus.a
lrwxrwxrwx 1 root root     16 Dec 17  2018 /usr/lib/x86_64-linux-gnu/libopus.so -> libopus.so.0.7.0
lrwxrwxrwx 1 root root     16 Dec 17  2018 /usr/lib/x86_64-linux-gnu/libopus.so.0 -> libopus.so.0.7.0
-rw-r--r-- 1 root root 370600 Dec 17  2018 /usr/lib/x86_64-linux-gnu/libopus.so.0.7.0

$ objdump -p /usr/lib/x86_64-linux-gnu/libopus.so | grep SONAME
  SONAME               libopus.so.0

I dont understand why libopus0 has version 1.3 ...?

perhaps we should also ask @jonassmedegaard from the Debian project for input.

Alfred

[jonassmedegaard]

The Debian package containing the runtime library has the major part of the SONAME in its package name and has the
upstream opus release version in its package version.

1.3 is version of upstream opus release
1.3-1 is version of Debian package (upstream version + Debian packaging revision)
0.7.0 is SONAME

Hope that helps.

[sreimers]

I updated the PR to count SONAME ABI Version independent and starting with libre.so.1 (prepared for next release).

[sreimers]

After some thought and research, I would prefer this versioning:

/usr/lib/libre.so -> libre.so.1.1.0
/usr/lib/libre.so.1 -> libre.so.1.1.0
/usr/lib/libre.so.1.1.0

$ objdump -p /usr/lib/libre.so | grep SONAME
  SONAME               libre.so.1

This corresponds to semantic versioning.
Breaking the ABI/API requires bumping the Major Version.

Sorry for the back and forth. But personally I use Libre only as static cross-platform builds
and had no preference for dynamic builds and soname versioning. Different projects uses
different approaches which is bit confusing, too.

The "/usr/lib/libre.so.1 -> libre.so.1.1.0" linking is done by ldconfig (soname field). As
mentioned here:

https://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html

[jonassmedegaard]

This text seems to decently clarify the distinction between project versions, APIs and ABIs, in case that's a help to some following along here: https://dcreager.net/shared-library-versions/

[sreimers]

Ok the author suggest to use a separate ABI shared library version info, the math is the following:

This flag accepts an argument of the form ‘current[:revision[:age]]’. So, passing -version-info 3:12:1 sets current to 3, revision to 12, and age to 1.

$major = $current - $age
versuffix=$major.$age.$revision
SOVERSION=$major

Here are a set of rules to help you update your library version information:

- Start with version information of ‘0:0:0’ for each libtool library.
- Update the version information only immediately before a public release of your software. More frequent updates are unnecessary, and only guarantee that the current interface number gets larger faster.
- If the library source code has changed at all since the last update, then increment revision (‘c:r:a’ becomes ‘c:r+1:a’).
- If any interfaces have been added, removed, or changed since the last update, increment current, and set revision to 0.
- If any interfaces have been added since the last public release, then increment age.
- If any interfaces have been removed or changed since the last public release, then set age to 0.

The following explanation may help to understand the above rules a bit better: consider that there are three possible kinds of reactions from users of your library to changes in a shared library:

- Programs using the previous version may use the new version as drop-in replacement, and programs using the new version can also work with the previous one. In other words, no recompiling nor relinking is needed. In this case, bump `revision` only, don’t touch `current` nor `age`.
- Programs using the previous version may use the new version as drop-in replacement, but programs using the new version may use APIs not present in the previous one. In other words, a program linking against the new version may fail with “unresolved symbols” if linking against the old version at runtime: set `revision` to 0, bump `current` and `age`.
- Programs may need to be changed, recompiled, and relinked in order to use the new version. Bump `current`, set `revision` and `age` to 0.

https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html

Opus uses the following:

# For libtool.
OPUS_LT_CURRENT=7
OPUS_LT_REVISION=0
OPUS_LT_AGE=7

-version-info @OPUS_LT_CURRENT@:@OPUS_LT_REVISION@:@OPUS_LT_AGE@