kicad-developers team mailing list archive

[Carsten Schoenert <c.schoenert@xxxxxxxxxxx>]

Hello Holger,

Am 27.07.21 um 14:03 schrieb Holger Vogt:
> So what would be the correct action?
> 
> When I compile ngspice, I get (besides libngspice.so.0.0.0 or 
> libngspice.so.0.0.1) two aliases libngspice.so.0 and libngspice.so. What 
> would be the correct version to link to?

there is nothing you need to do here (and you shouldn't do anything
here!), the correct linking of all relevant files is always done by
libtool as part of the intended versioning schema inside libtool based
on idea of ELF Symbol Versioning.

For those who are not really familiar with this I suggest to read some
old written stuff by Ulrich Drepper that explains some internals.

https://akkadia.org/drepper/symbol-versioning

libtool naming, something you need to remember every time if working
with the versioning for libraries.

libtool uses three elements to give a library a version.

1. Current  (== API version)
2. Revision (== iteration of the library)
3. Age      (== iteration on the availability of new symbols)

This built currently the following library for ngspice with it's full
name as all these elements using 0 for a version as nothing as a version
is given to the libtool call:

                  libngspice.so.0.0.0



And this is the schema that libtool is using to create the full name.

                current -------\     /------- revision
                                |   |
        shared object file --\  |   |
                  libngspice.so.0.0.0
                       |          |
        library name --/          |
                age -------------/


Looking at the output of libtool we see currently this if ngspice is
built with --with-ngshared:

> $ ls -l /usr/lib/x86_64-linux-gnu/libngspice*
> lrwxrwxrwx 1 root root      19 31. Jan 12:43 /usr/lib/x86_64-linux-gnu/libngspice.so -> libngspice.so.0.0.0
> lrwxrwxrwx 1 root root      19 31. Jan 12:43 /usr/lib/x86_64-linux-gnu/libngspice.so.0 -> libngspice.so.0.0.0
> -rw-r--r-- 1 root root 7340384 31. Jan 12:43 /usr/lib/x86_64-linux-gnu/libngspice.so.0.0.0

We see two links, the first one is the basic library name that is
pointing to the full version.
The other link is using an additional number which is simply '0' which
is also pointing to the full name.
This means these two links can only exist one time, but we can have
multiple full named libraries installed, the trick is the symlinking
here to point to the the most recent version normally.

Going back to the second link (libngspice.so.0 -> libngspice.so.0.0.0).
You might already see what this '0' means here, it's the number of
'Current' or also known as the API version.

Greater means breaking (non backward compatible) changes as also the API
has changed by this. This is happen e.g. if the maintainer has removed
symbols from the library for hopefully good reasons.

Now we are already by the compatibility of a library.

A library is backwards compatible if in a newer version all existing
symbols are still available and the behavior of the symbols doesn't have
changed. By this all old and existing applications can also use a newer
library version. And this is visible by the link of libngspice.so.0, the
number '0' means here exactly this.

What's if the maintainer has just done bug fixing or improved the
performance of the library? No new symbols were added and no existing
symbols have been modified or removed!
For this the new version needs to increase the revision. We would move
on from

libngspice.so.0.0.0   to    libngspice.so.0.0.1 (and so on)

And now the new library has become some new symbols, all existing
symbols stays the same as before.

Now the age needs to get increased and the revision falls back to 0. For
libngspice this would look like this.

libngspice.so.0.0.1   will go to    libngspice.so.0.1.0

And now the most intrusive thing that can happen, the new library has at
least one of there symbols removed. Remember, the library isn't
backwards compatible any longer! The API version has changed!
Current will get increased and revison and also age will get reset to '0'.

libngspice.so.0.1.0   will go to    libngspice.so.1.0.0

And libtool will create a new link named libngspice.so.1 pointing to the
new full named file.

If you doing this for the first time it's all a bit confusing as you can
see this all has nothing  to do with semver. But once you have
understand the idea it's quite obvious what needs to be done.

PS: I'm far away from being an expert in such things! Forgive me if
somethings isn't fully correct explained.

-- 
Regards
Carsten