Making new releases: libtool

[Richard B. Kreckel]

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/>
_______________________________________________
GiNaC-devel mailing list
GiNaC-devel@...
https://www.cebix.net/mailman/listinfo/ginac-devel

[Richard B. Kreckel]

Hi!

On Ralf Wildenhues' request I am bouncing his relpy herewith since he's
not subscribed to ginac-devel and his email was rejected.

   -richy.
--
Richard B. Kreckel
<http://www.ginac.de/~kreckel/>


_______________________________________________
GiNaC-devel mailing list
GiNaC-devel@...
https://www.cebix.net/mailman/listinfo/ginac-devel

[Richard B. Kreckel]

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/>
_______________________________________________
GiNaC-devel mailing list
GiNaC-devel@...
https://www.cebix.net/mailman/listinfo/ginac-devel

[Richard B. Kreckel]

Hi!

After Ralf's tutoring I propose this patch to GiNaC's configure.ac:

@@ -12,10 +12,11 @@ dnl version number. In particular, library version
is OS dependent.
  dnl
  dnl When making releases, do
  dnl 1. Increment ginac_lt_revision
-dnl 2. If any interfaces have been added, removed, or changed since the
last
-dnl    release, increment ginac_lt_current and set ginac_lt_revision to 0.
-dnl 3. If any interfaces have been removed since the last release, set
-dnl    ginac_lt_age to 0.
+dnl 2. If any interfaces have been added since the last release, increment
+dnl    ginac_lt_current and set ginac_lt_revision to 0.
+dnl 3. If any interfaces have been changed or removed since the last
release,
+dnl    make sure you increment ginac_minor_version above and reset both
+dnl    ginac_lt_current and ginac_lt_revision to 0.
  dnl
  dnl Please note: the libtool naming scheme cannot guarantee that on all
  dnl systems, the numbering is consecutive. It only guarantees that it is
@@ -23,7 +24,6 @@ dnl increasing. This doesn't matter, though: there is
not incurred cost
  dnl for numbers that are omitted, except for shrinking the available space
  dnl of leftover numbers. Not something we need to worry about yet. ;-)
  m4_define([ginac_lt_current], [0])
-m4_define([ginac_lt_age], [0])
  m4_define([ginac_lt_revision], [0])

  AC_INIT([GiNaC], ginac_version, [<ginac-list@...>])
@@ -57,8 +57,9 @@ AC_SUBST(ARCHIVE_AGE)
  AC_DEFINE_UNQUOTED(ARCHIVE_VERSION, $ARCHIVE_VERSION, [Current GiNaC
archive file version number])
  AC_DEFINE_UNQUOTED(ARCHIVE_AGE, $ARCHIVE_AGE, [GiNaC archive file
version age])

-dnl libtool versioning
-LT_VERSION_INFO="ginac_lt_current:ginac_lt_revision:ginac_lt_age"
+dnl libtool versioning (We don't use libtool's age numbering since we
promise
+dnl to keep the binary interface compatible if only ginac_micro_version
changes.)
+LT_VERSION_INFO="ginac_lt_current:ginac_lt_revision:0"
  LT_RELEASE="ginac_release"

  AC_SUBST(LT_VERSION_INFO)

Unless somebody objects, I'm going to commit this.

   -richy.
--
Richard B. Kreckel
<http://www.ginac.de/~kreckel/>
_______________________________________________
GiNaC-devel mailing list
GiNaC-devel@...
https://www.cebix.net/mailman/listinfo/ginac-devel