ABI backward compatibility enhancement

Use the libtool link mode argument '-version-info' to set the Hamlib 3
ABI to be compatible with Hamlib 1.2 ABI.  As the current ABI has not
been changed or removed, we should be able to maintain backward
compatibility.  The libtool docs state that so long as the ABI is only
added to, backward compatibility should be maintained.

My idea here is to be able to have presently compiled programs be able
to use binary libraries of Hamlib 3 without recompiling.  So far I have
tested this locally on Linux and Windows.  More testing is welcome.

.gitignore

@@ -6,6 +6,7 @@
 *.o
 *.lo
 *.la
+*.swp
 Makefile
 Makefile.in
 aclocal.m4

README.release

@@ -1,4 +1,3 @@
-
 This file is a release HOWTO, more or less a reminder before releasing
 a new version of Hamlib.
 
@@ -20,7 +19,7 @@ Before deciding release:
   of each year will provide about a month of testing before release.
 
 * Update the configuration:
-    clean the tree:
+    clean the tree (removing all files not tracked by Git):
         make dist clean; git clean -dxf
 
 Releasing Hamlib:
@@ -45,7 +44,7 @@ remote repository, "origin"):
   local repository to origin/master:
 
   $ git reset --hard origin/master
-  HEAD is now at 522229d chmod +x autogen.sh
+  HEAD is now at ??????? Last commit message summary
 
     Thanks, Kamal Mostafa, KA6MAL
 
@@ -56,21 +55,27 @@ remote repository, "origin"):
   git commit -a     # Commit all modified files locally
 
 * Create a new branch for the release:
-  git branch Hamlib-1.2.15
+  git branch Hamlib-3.1
 
 * Push the changes (check for validity):
   git push origin       # pushes previous commit to sf.net repository
-  git push -u origin Hamlib-1.2.15         # push the branch and set "upstream"
+  git push -u origin Hamlib-3.1         # push the branch and set "upstream"
 
 * Update the version in the macro AC_INIT of configure.ac (advance to next
-  version, e.g. 1.2.16~git) and the libhamlib_la_LDFLAGS value in
-  src/Makefile.am and c++/Makefile.am to match. e.g.:
-  libhamlib_la_LDFLAGS = $(WINLDFLAGS) $(OSXLDFLAGS) -no-undefined -version-info @ABI_VERSION@:16:0
+  version, e.g. 3.1~git) and the ABI_RELEASE value in configure.ac.
 
-  Note that -version-info is a libtool flag and reflects ABI compatibility.
-  In @ABI_VERSION@:16:0, ABI_VERSION is set in configure.ac, 16 is the
-  revision, and :0 should remain 0.  When the API is changed, ABI_VERSION
-  will be advanced, and revision (e.g. :16) will be reset to 0.
+  Note that -version-info is a libtool link mode argument and reflects ABI
+  compatibility between Hamlib releases.  The values of ABI_VERSION,
+  ABI_REVISION, and ABI_AGE are set in configure.ac. ABI_VERSION should be
+  advanced when the ABI is affected by changes in the library interface.
+  ABI_REVISION is the revision and indicates source changes in Hamlib but no
+  change in ABI.  ABI_AGE reflects backward compatibity to a previous version.
+  Per the libtool manual, this value is subtracted from ABI_VERSION to note
+  compatible prior versions.  Per the libtool manual, so long as the library
+  interface is added to and nothing is removed or changed, backward
+  compatibity should exist.  When the API is changed, ABI_VERSION will be
+  advanced, ABI_REVISION will be reset to 0, and ABI_AGE may be advanced
+  pending API/ABI changes.
 
   Format is ABI version:revision:age.  Setting age to other than 0 causes
   strange DLL naming in Win32 cross-compile builds.
@@ -84,7 +89,7 @@ which will be advanced for the next release candidate or stripped for final
 release:
 
 * Checkout the release branch:
-  git checkout Hamlib-1.2.15
+  git checkout Hamlib-3.1
 
 * Edit config.ac, commit it and push it.  The branch is now ready for
   rc testing/release.
@@ -93,7 +98,7 @@ release:
     ./autogen.sh
     make dist
 
-    The resulting tarball--hamlib-1.x.y[.z].tar.gz--should be tested as much
+    The resulting tarball--hamlib-3.y[.z].tar.gz--should be tested as much
     as possible to assure compilation integrity. etc.
 
 
@@ -113,8 +118,8 @@ See README.build-win32 for information on prerequisites, etc.
 * Release the file(s)
   - https://sourceforge.net/projects/hamlib/files/
   - Select Hamlib
-  - Click Add Folder, name it X.Y.Z[.a]
-  - Select X.Y.Z[.a]
+  - Click Add Folder, name it X.Y[.Z]
+  - Select X.Y[.Z]
   - Click Add File button
   - Click Choose File button
   - Click Upload

c++/Makefile.am

@@ -1,7 +1,7 @@
 
 lib_LTLIBRARIES = libhamlib++.la
 libhamlib___la_SOURCES = rigclass.cc rotclass.cc
-libhamlib___la_LDFLAGS = -no-undefined -version-info @ABI_VERSION@:0:0
+libhamlib___la_LDFLAGS = -no-undefined -version-info @ABI_VERSION@:@ABI_REVISION@:@ABI_AGE@
 libhamlib___la_LIBADD = $(top_builddir)/src/libhamlib.la
 
 check_PROGRAMS = testcpp

configure.ac

@@ -47,16 +47,26 @@ dnl added to AC_CONFIG_FILES near the end of this file.  See README.developer
 BACKEND_LIST="icom kenwood aor yaesu dummy pcr alinco uniden tentec kachina jrc drake lowe rft rs kit skanti prm80 tapr flexradio wj racal tuner adat"
 ROT_BACKEND_LIST="dummy easycomm fodtrack gs232a heathkit kit rotorez sartek spid ars m2 amsat ts7400 celestron"
 
+dnl See README.release on setting these values
+# Values given to -version-info when linking.  See libtool documentation.
+# Set them here to keep c++/Makefile and src/Makefile in sync.
 ABI_VERSION=3
+ABI_REVISION=0
+ABI_AGE=1
 
 AC_DEFINE_UNQUOTED([ABI_VERSION], [$ABI_VERSION], [Frontend ABI version])
+AC_DEFINE_UNQUOTED([ABI_REVISION], [$ABI_REVISION], [Frontend ABI revision])
+AC_DEFINE_UNQUOTED([ABI_AGE], [$ABI_AGE], [Frontend ABI age])
+
 AC_SUBST([ABI_VERSION])
+AC_SUBST([ABI_REVISION])
+AC_SUBST([ABI_AGE])
 
 dnl Pick up the Hamlib macros.
 dnl macros/aclocal-include.m4
 dnl AM_ACLOCAL_INCLUDE([macros])
 
-dnl directory for docs (html)
+# directory for docs (html)
 hamlibdocdir=$datadir/doc/hamlib
 AC_SUBST([hamlibdocdir])
 
@@ -76,7 +86,7 @@ AC_PROG_INSTALL
 AC_PROG_LN_S
 AC_PROG_MAKE_SET
 
-dnl Pkgconfig
+dnl Pkgconfig assists when using certain external packages
 PKG_PROG_PKG_CONFIG
 
 dnl AC_AIX
@@ -92,7 +102,6 @@ dnl     you adjust the code.  You can also remove the above call to
 dnl     AC_PROG_CC if you already called it elsewhere.])
 dnl am_cv_prog_cc_stdc=$ac_cv_prog_cc_stdc
 
-
 ## ----------------------------------- ##
 ## Miscellaneous configuration macros  ##
 ## ----------------------------------- ##

src/Makefile.am

@@ -10,7 +10,7 @@ RIGSRC = rig.c serial.c misc.c register.c event.c cal.c conf.c tones.c \
 
 lib_LTLIBRARIES = libhamlib.la
 libhamlib_la_SOURCES = $(RIGSRC)
-libhamlib_la_LDFLAGS = $(WINLDFLAGS) $(OSXLDFLAGS) -no-undefined -version-info @ABI_VERSION@:0:0
+libhamlib_la_LDFLAGS = $(WINLDFLAGS) $(OSXLDFLAGS) -no-undefined -version-info @ABI_VERSION@:@ABI_REVISION@:@ABI_AGE@
 libhamlib_la_CFLAGS = -DIN_HAMLIB $(AM_CFLAGS) -DHAMLIB_MODULE_DIR=\"$(pkglibdir)\"
 
 # $(LIBLTDL) is set by LTDL_INIT macro