Implement libtool library versioning.

Use maximum proc_nr (MAX_PROC_NR) as a surrogate for the
library ABI version, resulting in version numbers such as
libguestfs.so.0.<MAX_PROC_NR>.0 for the final library.

Add ABI guarantee to the documentation.

configure.ac

@@ -497,6 +497,10 @@ fi
 AM_CONDITIONAL([HAVE_INSPECTOR],
     [test "x$PERL" != "xno" -a "x$missing_perl_modules" != "xyes"])
 
+dnl Library versioning.
+MAX_PROC_NR=`cat $srcdir/src/MAX_PROC_NR`
+AC_SUBST(MAX_PROC_NR)
+
 dnl Run in subdirs.
 AC_CONFIG_SUBDIRS([daemon])
 

guestfs.pod

@@ -205,6 +205,14 @@ search the current directory and then C</usr/lib/guestfs>.
 
 =head1 HIGH-LEVEL API ACTIONS
 
+=head2 ABI GUARANTEE
+
+We guarantee the libguestfs ABI (binary interface), for public,
+high-level actions as outlined in this section.  Although we will
+deprecate some actions, for example if they get replaced by newer
+calls, we will keep the old actions forever.  This allows you the
+developer to program in confidence against libguestfs.
+
 @ACTIONS@
 
 =head1 STRUCTURES

src/MAX_PROC_NR

@@ -0,0 +1 @@
+116

src/Makefile.am

@@ -25,7 +25,49 @@ include_HEADERS = guestfs.h guestfs-actions.h guestfs-structs.h
 
 lib_LTLIBRARIES = libguestfs.la
 
-libguestfs_la_LDFLAGS = -version-info 0:0:0
+# From the libtool info file, with comments:
+#
+# |  1. Start with version information of `0:0:0' for each libtool library.
+# |
+# |  2. Update the version information only immediately before a public
+# |     release of your software.  More frequent updates are unnecessary,
+# |     and only guarantee that the current interface number gets larger
+# |     faster.
+# |
+# |  3. If the library source code has changed at all since the last
+# |     update, then increment REVISION (`C:R:A' becomes `C:r+1:A').
+#
+# [So it seems like we should always update the middle 'R' field
+# for any release.]
+#
+# |  4. If any interfaces have been added, removed, or changed since the
+# |     last update, increment CURRENT, and set REVISION to 0.
+# |
+# |  5. If any interfaces have been added since the last public release,
+# |     then increment AGE.
+#
+# [These two rules seem to mean that if any change is made to the
+# generator, we should increment C and A, and set R to 0, so:
+# C+1:0:A+1.]
+#
+# |  6. If any interfaces have been removed since the last public release,
+# |     then set AGE to 0.
+#
+# [Our ABI guarantee means we won't remove interfaces except in
+# very exceptional circumstances.]
+#
+# The maximum proc number (see guestfs_protocol.x:guestfs_procedure) is
+# a mostly accurate stand-in for C & A in rules 5 & 6, so we use that.  It
+# is always incremented when we add a new appliance interface, and easy to
+# calculate.
+#
+# The middle number is hard to increment-and-reset as described in rules
+# 4 & 5, so for the moment it is always set to 0.
+#
+# Note that this scheme means the real library version will always be
+# 'libguestfs.so.0.$(MAX_PROC_NR).0'.
+
+libguestfs_la_LDFLAGS = -version-info $(MAX_PROC_NR):0:$(MAX_PROC_NR)
 libguestfs_la_SOURCES = \
 	guestfs.c \
 	guestfs.h \

src/generator.ml

@@ -7829,6 +7829,19 @@ and generate_lang_bindtests call =
 
   (* XXX Add here tests of the return and error functions. *)
 
+(* This is used to generate the src/MAX_PROC_NR file which
+ * contains the maximum procedure number, a surrogate for the
+ * ABI version number.  See src/Makefile.am for the details.
+ *)
+and generate_max_proc_nr () =
+  let proc_nrs = List.map (
+    fun (_, _, proc_nr, _, _, _, _) -> proc_nr
+  ) daemon_functions in
+
+  let max_proc_nr = List.fold_left max 0 proc_nrs in
+
+  pr "%d\n" max_proc_nr
+
 let output_to filename =
   let filename_new = filename ^ ".new" in
   chan := open_out filename_new;
@@ -8001,3 +8014,7 @@ Run it from the top source directory using the command
   let close = output_to "haskell/bindtests.hs" in
   generate_haskell_bindtests ();
   close ();
+
+  let close = output_to "src/MAX_PROC_NR" in
+  generate_max_proc_nr ();
+  close ();