From d3270cfadd3416bd9961a2c6fb1cc131c43979da Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Tue, 23 Jun 2009 22:02:10 +0100 Subject: [PATCH] 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..0 for the final library. Add ABI guarantee to the documentation. --- configure.ac | 4 ++++ guestfs.pod | 8 ++++++++ src/MAX_PROC_NR | 1 + src/Makefile.am | 44 +++++++++++++++++++++++++++++++++++++++++++- src/generator.ml | 17 +++++++++++++++++ 5 files changed, 73 insertions(+), 1 deletion(-) create mode 100644 src/MAX_PROC_NR diff --git a/configure.ac b/configure.ac index ec64cd3..91e4792 100644 --- a/configure.ac +++ b/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]) diff --git a/guestfs.pod b/guestfs.pod index 10c6ad8..3dad35c 100644 --- a/guestfs.pod +++ b/guestfs.pod @@ -205,6 +205,14 @@ search the current directory and then C. =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 diff --git a/src/MAX_PROC_NR b/src/MAX_PROC_NR new file mode 100644 index 0000000..4699eb3 --- /dev/null +++ b/src/MAX_PROC_NR @@ -0,0 +1 @@ +116 diff --git a/src/Makefile.am b/src/Makefile.am index c310c9c..6b1088c 100644 --- a/src/Makefile.am +++ b/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 \ diff --git a/src/generator.ml b/src/generator.ml index f1a9a45..51d3235 100755 --- a/src/generator.ml +++ b/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 (); -- 1.8.3.1