Re: Improve versioning algorithm description
* Bob Friesenhahn wrote on Wed, Sep 23, 2009 at 05:19:26AM CEST: On Tue, 22 Sep 2009, Ralf Wildenhues wrote: The current text in the Updating version info node is seen as hard to understand by some users, IIRC we've had a few reports about this in the past. Richard made me try to reformulate it now. What do you think about this additional explanation? OK to apply (and ok to add you to THANKS, Richard)? This explanation is very useful. Please apply. Pushed now. Sorry for the long delay. Cheers, Ralf Improve versioning algorightm documentation. * doc/libtool.texi (Updating version info): Repeat the algorithms in different, hopefully simpler terms. * THANKS: Update. Report by Richard B. Kreckel and others, several times.
Improve versioning algorithm description
The current text in the Updating version info node is seen as hard to
understand by some users, IIRC we've had a few reports about this in the
past. Richard made me try to reformulate it now.
What do you think about this additional explanation?
OK to apply (and ok to add you to THANKS, Richard)?
Thanks,
Ralf
Improve versioning algorightm documentation.
* doc/libtool.texi (Updating version info): Repeat the
algorithms in different, hopefully simpler terms.
* THANKS: Update.
Report by Richard B. Kreckel and others, several times.
diff --git a/doc/libtool.texi b/doc/libtool.texi
index 08a44c4..cb6ec80 100644
--- a/doc/libtool.texi
+++ b/doc/libtool.texi
@@ -2879,6 +2879,37 @@ Instead, use the @option{-release} flag (@pxref{Release
numbers}), but be
warned that every release of your package will not be binary compatible
with any other release.
+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:
+
+...@enumerate 1
+...@item
+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 @var{revision} only, don't touch
+...@var{current} nor @var{age}.
+
+...@item
+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 @var{revision} to 0, bump @var{current}
+and @var{age}.
+
+...@item
+Programs may need to be changed, recompiled, relinked in order to use
+the new version. Bump @var{current}, set @var{revision} and @var{age}
+to 0.
+...@end enumerate
+
+...@noindent
+In the above description, @emph{programs} using the library in question
+may also be replaced by other libraries using it.
+
+
@node Release numbers
@section Managing release information
Re: Improve versioning algorithm description
On Tue, 22 Sep 2009, Ralf Wildenhues wrote:
The current text in the Updating version info node is seen as hard to
understand by some users, IIRC we've had a few reports about this in the
past. Richard made me try to reformulate it now.
What do you think about this additional explanation?
OK to apply (and ok to add you to THANKS, Richard)?
This explanation is very useful. Please apply.
Bob
Improve versioning algorightm documentation.
* doc/libtool.texi (Updating version info): Repeat the
algorithms in different, hopefully simpler terms.
* THANKS: Update.
Report by Richard B. Kreckel and others, several times.
diff --git a/doc/libtool.texi b/doc/libtool.texi
index 08a44c4..cb6ec80 100644
--- a/doc/libtool.texi
+++ b/doc/libtool.texi
@@ -2879,6 +2879,37 @@ Instead, use the @option{-release} flag (@pxref{Release
numbers}), but be
warned that every release of your package will not be binary compatible
with any other release.
+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:
+
+...@enumerate 1
+...@item
+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 @var{revision} only, don't touch
+...@var{current} nor @var{age}.
+
+...@item
+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 @var{revision} to 0, bump @var{current}
+and @var{age}.
+
+...@item
+Programs may need to be changed, recompiled, relinked in order to use
+the new version. Bump @var{current}, set @var{revision} and @var{age}
+to 0.
+...@end enumerate
+
+...@noindent
+In the above description, @emph{programs} using the library in question
+may also be replaced by other libraries using it.
+
+
@node Release numbers
@section Managing release information
--
Bob Friesenhahn
bfrie...@simple.dallas.tx.us, http://www.simplesystems.org/users/bfriesen/
GraphicsMagick Maintainer,http://www.GraphicsMagick.org/
Re: Improve versioning algorithm description
Hi Bob, * Bob Friesenhahn wrote on Wed, Sep 23, 2009 at 05:19:26AM CEST: On Tue, 22 Sep 2009, Ralf Wildenhues wrote: The current text in the Updating version info node is seen as hard to understand by some users, IIRC we've had a few reports about this in the past. Richard made me try to reformulate it now. What do you think about this additional explanation? OK to apply (and ok to add you to THANKS, Richard)? This explanation is very useful. Please apply. The most important question is whether it is correct, not only for Linux. That's what I'm not yet certain about. Thanks, Ralf
Re: Improve versioning algorithm description
* Bob Friesenhahn wrote on Wed, Sep 23, 2009 at 05:47:55AM CEST: On Wed, 23 Sep 2009, Ralf Wildenhues wrote: The most important question is whether it is correct, not only for Linux. That's what I'm not yet certain about. Something tells me that it is not correct for Windows. Under Windows I see a lack of versioning and libtool adds a simple number like name-7.dll to the name. Not all OSs support library versioning, so in that case applications would continue using the older library and freshly compiled applications would use the newer library. That is the same with systems which only provide static linkage. We cannot do anything against that; only, we shouldn't imply in the documentation that the user can expect anything better either. Aside, most systems where $major is not $current-$age will need relinking after a compatible API update (case 2). This is the more relevant case I'm thinking of, I guess most users know about the case of totally featureless versioning. Cheers, Ralf
Re: Improve versioning algorithm description
Bob Friesenhahn wrote: On Wed, 23 Sep 2009, Ralf Wildenhues wrote: The most important question is whether it is correct, not only for Linux. That's what I'm not yet certain about. Something tells me that it is not correct for Windows. Ralf's description is correct also for Windows. Under Windows I see a lack of versioning and libtool adds a simple number like name-7.dll to the name. Not all OSs support library versioning, so in that case applications would continue using the older library and freshly compiled applications would use the newer library. Thru the magic of 'c-a', on windows we can represent one dimensional compatibility (that is, backwards compatibility) with a single number. That is: old app -- old dll, ok. old app -- new compatible dll, ok new app -- new compatible dll, ok new app -- old dll, maybe ok, maybe not. The old dll may not be forward compatible with new applications, even though the new dll is backwards compatible with old applications, and thus both DLLs have the same single number. From Ralf's three cases: case 1) no API change at all, c and a do not change -- DLL is forward- and backward- compatible, and 'c-a' remains constant so DLL name doesn't change. This is correct behavior. case 2) API additions only. DLL is backwards-compatible, but not forward-compatible. Both c and a are incremented, so 'c-a' does not change, and DLL name doesn't change. This is correct behavior. case 3) API deletions or modifications. DLL is not compatible. c in incremented, and a is set to 0. No matter how you slice it, 'c-a' will change -- and the DLL name will change with it. This is correct behavior. See this page for a good example: http://home.att.net/~perlspinr/libversioning.html -- Chuck
