[Openal-devel] SI Releases?

[Eddy [the Obsessed] Cullen]

Chris Robinson wrote:
> On Monday 13 August 2007 01:05:26 pm Eddy [the Obsessed] Cullen wrote:
>> Version numbering
>> =================
>>
>> Please read the Linux Program Library HOWTO at
>> http://tldp.org/HOWTO/Program-Library-HOWTO/
>>
>> Basically, the micro (patch) version should be strictly incremental, so
>> that sysadmins know which the latest version is.
> 
> That page isn't terribly clear. I looks like it says that you have the base 
> libfoo.X name, and X should be incremented whenever the interface changes. 
> The OpenAL API is good about keeping backwards compatibility, so does even 
> adding a new function while leaving the others alone, constitute a change?

The short answer is no, only *adding* APIs *should* not require
incrementing the X, if it does, then it should be considered a bug.

The long answer has two parts to it - version numbering and library naming.

Version numbering is arbitrary, however, the preferred convention is to
use GNU-style MAJOR.MINOR.PATCH numbering. (Which, annoyingly, Gnome
libraries have the greatest habit of breaking, incidentally...)

MAJOR defines "binary compatibility"
MINOR defines "capabilities"
PATCH defines "patch level"

"Binary Compatibility" means that a binary compiled against this major
version number will continue to work with future versions, that is, a
program compiled against 1.0.0 should work with 1.9.0 *without
recompilation*

"Capabilities" refers to the status of the interface; version 1.1.0
implies APIs have be added to version 1.0.0, without breaking binary
compatibility.

"Patch level" can mean anything; build number, release number of a
particular major.minor combination. The key thing is that it REALLY
SHOULD be *strictly incremental*. Personally, I prefer the simple
release number; 1.0.0 will be followed by 1.0.1, etc. However, I would
also be happy with the the SVN version number of the TAG associated with
a release (releases should be tagged...), which is actually quite
tricky, as you don't get the tag until you've done the commit and anyone
can do a commit (e.g. on a branch) before you make yours...

As for filenames, you have 3 'files', where X is a number:

1) libfoo.so
2) libfoo.so.X
3) libfoo.so.X.X.X

3) is the 'real name'; the actual library file and would have the full
version number appended.

2) is the 'soname' the number. The number is the major part of the version.

1) is the 'linker name' and is used when linking the file.

1) & 2) are normally symlinks, to save space.

When you pass the linker the the library name as, e.g. '-lfoo', it
resolves it to the 'soname' and embeds this into the binary. Therefore,
when you want to use the binary, it must be able to find 'libfoo.so.X'

Assuming that you have a libfoo.so.X newer than the one used to build
the binary, it should work (because you've been careful to maintain
binary compatibility in libfoo.so.X).

This strategy works best when you have libfoo.X and libfoo.Y. You could
have libfoo.so -> libfoo.Y so NEW programs are compiled against
libfoo.so.Y, but old ones, linked against libfoo.X will continue to work.

Hope this helps,

Eddy