Making new releases: libtool
Hi Ralf! I just figured I would like to make a new release of CLN. I then realized that setting version numbers has always been confusing me. Until now, I've never cared as much about this as I should, but this should some day get clarified. The configure.ac file in CLN says: dnl * increment CL_REVISION, dnl * if any functions/classes have been added, removed or changed, dnl increment CL_CURRENT and set CL_REVISION to 0, dnl * if any functions/classes have been added, increment CL_AGE, dnl * if backwards compatibility has been broken, set CL_AGE to 0. dnl $(CL_CURRENT):$(CL_REVISION):$(CL_AGE) results in dnl libcln.so.$(CL_CURRENT)-$(CL_AGE) Okay, let's see. I've fixed a function that used to segfault and I've added support for a platform that was not supported before. I increment CL_REVISION. Have I added, removed ro changed a function or class? I'm not sure. Interface-wise not. But I've changed functionality (it doesn't crash any more). So I increment CL_CURRENT to 7 and set CL_REVISION to 0. I haven't added functions/classes, so I don't touch CL_AGE. And I haven't broken backwards compatibility, so I leave CL_AGE at 0. This results in libcln.so.7.0.0, which is clearly bogus, since the new version is a drop-in replacement for the old one! So, back to the second item: Maybe I shoudn't have incremented CL_CURRENT. Then, CL_REVISION is still 0. I haven't added functions/classes, so CL_AGE remains at 0, and I haven't broken backwards compatibility. Oops, then all version numbers remain the same. This is bogus, too! The confugure.ac file in GiNaC is slightly less ambiguous: dnl When making releases, do dnl 1. Increment ginac_lt_revision dnl 2. If any interfaces have been added, removed, or changed since the dnl last release, increment ginac_lt_current and set dnl ginac_lt_revision to 0. dnl 3. If any interfaces have been removed since the last release, set dnl ginac_lt_age to 0. Let's see what happens when I apply this to the new CLN release. This is more clear, since it refers to "interfaces" as opposed to "functions/classes". So I end up with REVISION=1, CURRENT=6 (as before), and AGE=0. This looks better and results in libcln.so.6.0.1. But is this correct? AGE is never incremented! Can you suggest better texts for configure.ac, so making new releases becomes painless? I shamefully have to admit that reading the libtool documentation did not really enlighten me. Regards -richy. -- Richard B. Kreckel <http://www.ginac.de/~kreckel/>
Hi Richard, * Richard B. Kreckel wrote on Sun, Sep 20, 2009 at 10:28:25PM CEST:
I just figured I would like to make a new release of CLN. I then realized that setting version numbers has always been confusing me. Until now, I've never cared as much about this as I should, but this should some day get clarified.
The configure.ac file in CLN says: [ pretty much a copy of 'info Libtool "Updating version info"' ]
dnl * increment CL_REVISION,
dnl * if any functions/classes have been added, removed or changed, dnl increment CL_CURRENT and set CL_REVISION to 0,
dnl * if any functions/classes have been added, increment CL_AGE,
dnl * if backwards compatibility has been broken, set CL_AGE to 0.
OK so far.
dnl $(CL_CURRENT):$(CL_REVISION):$(CL_AGE) results in
dnl libcln.so.$(CL_CURRENT)-$(CL_AGE)
This is not necessarily true. It only holds on some systems, but not on all.
Okay, let's see. I've fixed a function that used to segfault and I've added support for a platform that was not supported before. I increment CL_REVISION.
OK.
Have I added, removed ro changed a function or class? I'm not sure. Interface-wise not. But I've changed functionality (it doesn't crash any more). So I increment CL_CURRENT to 7 and set CL_REVISION to 0.
Why? I'd only do that if the crash was part of previously documented behavior, i.e., intentional, and that users of the old version of your library rely on it crashing, and need to change their code and recompile/relink to use the new version. If all you've done is a bugfix then I don't see why your interface has changed. So all you do from the previous release is bump up CL_REVISION, and not touch the rest. The whole thing is pretty simple if you consider that there are three possible kinds of reactions from your users to changes from you: 1) Programs using the previous version may use the new version as drop-in and programs using the new version can also work with the previous one. IOW, no recompiling, no relinking needed. In this case, bump REVISION only. 2) Programs using the previous version may use the new version as drop-in but Programs using the new version may use APIs not present in the previous one. IOW, a program linking against the new version may fail with "unresolved symbols" if linking against the old version at runtime: REVISION = 0, bump CURRENT and AGE. 3) Programs may need to be changed, recompiled, relinked in order to use the new version. REVISION = 0, bump CURRENT, AGE = 0. HTH. We should probably add something like that to the Libtool manual, but for that I should think about this a bit more, in case I overlooked something. Cheers, Ralf
Hi Ralf! Ralf Wildenhues wrote:
Have I added, removed ro changed a function or class? I'm not sure. Interface-wise not. But I've changed functionality (it doesn't crash any more). So I increment CL_CURRENT to 7 and set CL_REVISION to 0.
Why? I'd only do that if the crash was part of previously documented behavior, i.e., intentional, and that users of the old version of your library rely on it crashing, and need to change their code and recompile/relink to use the new version. If all you've done is a bugfix then I don't see why your interface has changed. So all you do from the previous release is bump up CL_REVISION, and not touch the rest.
I find the phrase "functions/classes have been changed" rather confusing. It is unclear what "changed" means.
The whole thing is pretty simple if you consider that there are three possible kinds of reactions from your users to changes from you:
1) Programs using the previous version may use the new version as drop-in and programs using the new version can also work with the previous one. IOW, no recompiling, no relinking needed. In this case, bump REVISION only.
2) Programs using the previous version may use the new version as drop-in but Programs using the new version may use APIs not present in the previous one. IOW, a program linking against the new version may fail with "unresolved symbols" if linking against the old version at runtime: REVISION = 0, bump CURRENT and AGE.
3) Programs may need to be changed, recompiled, relinked in order to use the new version. REVISION = 0, bump CURRENT, AGE = 0.
HTH. We should probably add something like that to the Libtool manual, but for that I should think about this a bit more, in case I overlooked something.
Thank you! And please add this to the Libtool manual. This explanation is so much easier to understand than the existing one. Cheers -richy. -- Richard B. Kreckel <http://www.ginac.de/~kreckel/>
participants (2)
-
Ralf Wildenhues
-
Richard B. Kreckel