build: Start using library versioning for various libraries

According to libtool three individual numbers stand for
CURRENT:REVISION:AGE, or C:R:A for short. The libtool
script typically tacks these three numbers onto the end
of the name of the .so file it creates. The formula for
calculating the file numbers on Linux and Solaris is

   /path/to/library/<library_name>.(C - A).(A).(R)

As you release new versions of your library, you will
update the library's C:R:A. Although the rules for changing
these version numbers can quickly become confusing, a few
simple tips should help keep you on track. The libtool
documentation goes into greater depth.

In essence, every time you make a change to the library and
release it, the C:R:A should change. A new library should start
with 0:0:0. Each time you change the public interface
(i.e., your installed header files), you should increment the
CURRENT number. This is called your interface number. The main
use of this interface number is to tag successive revisions
of your API.

The AGE number is how many consecutive versions of the API the
current implementation supports. Thus if the CURRENT library
API is the sixth published version of the interface and it is
also binary compatible with the fourth and fifth versions
(i.e., the last two), the C:R:A might be 6:0:2. When you break
binary compatibility, you need to set AGE to 0 and of course
increment CURRENT.

The REVISION marks a change in the source code of the library
that doesn't affect the interface-for example, a minor bug fix.
Anytime you increment CURRENT, you should set REVISION back to 0.

Change-Id: Id72e74c1642c804fea6f93ec109135c7c16f1810
BUG: 862082
Signed-off-by: Harshavardhana <harsha@harshavardhana.net>
Reviewed-on: http://review.gluster.org/5645
Tested-by: Gluster Build System <jenkins@build.gluster.com>
Reviewed-by: Niels de Vos <ndevos@redhat.com>
Reviewed-by: Vijay Bellur <vbellur@redhat.com>

diff --git a/api/src/Makefile.am b/api/src/Makefile.am
index 7c5df3e20298f8a7685abce14cd78e60b3fda926..c9992d1d3639839eb5fb4c2d947046da2d0ecd70 100644 (file)
--- a/api/src/Makefile.am
+++ b/api/src/Makefile.am
@@ -15,6 +15,7 @@ libgfapi_la_CPPFLAGS = $(GF_CPPFLAGS) -D__USE_FILE_OFFSET64 \
        -I$(top_srcdir)/rpc/rpc-lib/src \
        -I$(top_srcdir)/rpc/xdr/src
 
+libgfapi_la_LDFLAGS = -version-info $(GFAPI_LT_VERSION)
 
 xlator_LTLIBRARIES = api.la
 xlatordir = $(libdir)/glusterfs/$(PACKAGE_VERSION)/xlator/mount

diff --git a/configure.ac b/configure.ac
index be1ec7ab67074137edd1a358d34d822c61c3802d..abcf99ac95c48403e03c8c4bd707b2a9e4600153 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -888,6 +888,24 @@ AM_CONDITIONAL([GF_DARWIN_HOST_OS], test "${GF_HOST_OS}" = "GF_DARWIN_HOST_OS")
 
 AM_CONDITIONAL([GF_INSTALL_VAR_LIB_GLUSTERD], test ! -d ${localstatedir}/lib/glusterd && test -d ${sysconfdir}/glusterd )
 
+dnl pkg-config versioning
+GFAPI_VERSION="0.0.6"
+LIBGFCHANGELOG_VERSION="0.0.1"
+AC_SUBST(GFAPI_VERSION)
+AC_SUBST(LIBGFCHANGELOG_VERSION)
+
+dnl libtool versioning
+LIBGFXDR_LT_VERSION="0:1:0"
+LIBGFRPC_LT_VERSION="0:1:0"
+LIBGLUSTERFS_LT_VERSION="0:1:0"
+LIBGFCHANGELOG_LT_VERSION="0:1:0"
+GFAPI_LT_VERSION="0:6:0"
+AC_SUBST(LIBGFXDR_LT_VERSION)
+AC_SUBST(LIBGFRPC_LT_VERSION)
+AC_SUBST(LIBGLUSTERFS_LT_VERSION)
+AC_SUBST(LIBGFCHANGELOG_LT_VERSION)
+AC_SUBST(GFAPI_LT_VERSION)
+
 AC_OUTPUT
 
 echo

diff --git a/doc/versioning.md b/doc/versioning.md
new file mode 100644 (file)
index 0000000..10c1511
--- /dev/null
+++ b/doc/versioning.md
@@ -0,0 +1,44 @@
+Versioning
+==========
+
+### current
+
+The number of the current interface exported by the library. A current value
+of '1', means that you are calling the interface exported by this library
+interface 1.
+
+### revision
+
+The implementation number of the most recent interface exported by this library.
+In this case, a revision value of `0` means that this is the first
+implementation of the interface.
+
+If the next release of this library exports the same interface, but has a
+different implementation (perhaps some bugs have been fixed), the revision
+number will be higher, but current number will be the same. In that case, when
+given a choice, the library with the highest revision will always be used by
+the runtime loader.
+
+### age
+
+The number of previous additional interfaces supported by this library. If age
+were '2', then this library can be linked into executables which were built with
+a release of this library that exported the current interface number, current,
+or any of the previous two interfaces. By definition age must be less than or
+equal to current. At the outset, only the first ever interface is implemented,
+so age can only be `0'.
+
+For every release of the library `-version-info` argument needs to be set
+correctly depending on any interface changes you have made.
+
+This is quite straightforward when you understand what the three numbers mean:
+
+If you have changed any of the sources for this library, the revision number
+must be incremented. This is a new revision of the current interface. If the
+interface has changed, then current must be incremented, and revision reset
+to '0'.
+
+This is the first revision of a new interface. If the new interface is a
+superset of the previous interface (that is, if the previous interface has not
+been broken by the changes in this new release), then age must be incremented.
+This release is backwards compatible with the previous release.

diff --git a/glusterfs-api.pc.in b/glusterfs-api.pc.in
index fab4a57d59c707756f7da1da26e9d0de3823e55e..e88e70369ff21f30d8f41b0c76bd84b573af4896 100644 (file)
--- a/glusterfs-api.pc.in
+++ b/glusterfs-api.pc.in
@@ -3,10 +3,9 @@ exec_prefix=@exec_prefix@
 libdir=@libdir@
 includedir=@includedir@
 
-
 Name: glusterfs-api
 Description: GlusterFS API
 /* This is the API version, NOT package version */
-Version: 6
+Version: @GFAPI_VERSION@
 Libs: -L${libdir} -lgfapi -lglusterfs -lgfrpc -lgfxdr
 Cflags: -I${includedir}/glusterfs -D_FILE_OFFSET_BITS=64 -D__USE_FILE_OFFSET64

diff --git a/libgfchangelog.pc.in b/libgfchangelog.pc.in
index d654280d056adf2beea1b7315845b7ddfcd20d08..398f1233ffed06f296335d3abe8799cc56e96fc7 100644 (file)
--- a/libgfchangelog.pc.in
+++ b/libgfchangelog.pc.in
@@ -6,6 +6,6 @@ includedir=@includedir@
 
 Name: libgfchangelog
 Description: GlusterFS Changelog Consumer Library
-Version: @VERSION@
+Version: @LIBGFCHANGELOG_VERSION@
 Libs: -L${libdir} -lgfchangelog -lglusterfs
 Cflags: -I${includedir}/glusterfs/gfchangelog -D_FILE_OFFSET_BITS=64 -D__USE_FILE_OFFSET64

diff --git a/libglusterfs/src/Makefile.am b/libglusterfs/src/Makefile.am
index 907399ae601d2a8890c1b6c3297956af406dd760..634e217ed4d20b518aa1dc8b4271da14e7aece3f 100644 (file)
--- a/libglusterfs/src/Makefile.am
+++ b/libglusterfs/src/Makefile.am
@@ -7,6 +7,7 @@ libglusterfs_la_CPPFLAGS = $(GF_CPPFLAGS) -D__USE_FILE_OFFSET64 \
        -I$(top_srcdir)/rpc/rpc-lib/src/ -I$(CONTRIBDIR)/rbtree
 
 libglusterfs_la_LIBADD = @LEXLIB@
+libglusterfs_la_LDFLAGS = -version-info $(LIBGLUSTERFS_LT_VERSION)
 
 lib_LTLIBRARIES = libglusterfs.la
 

diff --git a/rpc/rpc-lib/src/Makefile.am b/rpc/rpc-lib/src/Makefile.am
index f19c3c8a43133272c271b44c22f560d26e37bc90..4cdeaad0b4d35da8fb1d1e67f5741e9b39c47c3a 100644 (file)
--- a/rpc/rpc-lib/src/Makefile.am
+++ b/rpc/rpc-lib/src/Makefile.am
@@ -5,6 +5,7 @@ libgfrpc_la_SOURCES = auth-unix.c rpcsvc-auth.c rpcsvc.c auth-null.c \
        rpc-drc.c
 
 libgfrpc_la_LIBADD = $(top_builddir)/libglusterfs/src/libglusterfs.la
+libgfrpc_la_LDFLAGS = -version-info $(LIBGFRPC_LT_VERSION)
 
 noinst_HEADERS = rpcsvc.h rpc-transport.h xdr-common.h xdr-rpc.h xdr-rpcclnt.h \
        rpc-clnt.h rpcsvc-common.h protocol-common.h rpc-drc.h

diff --git a/rpc/xdr/src/Makefile.am b/rpc/xdr/src/Makefile.am
index 949e75e8d702510b8188327440c0077815013640..0ec96e464baa30782904eb810e4266d591d79045 100644 (file)
--- a/rpc/xdr/src/Makefile.am
+++ b/rpc/xdr/src/Makefile.am
@@ -8,6 +8,8 @@ libgfxdr_la_CPPFLAGS = $(GF_CPPFLAGS) -D__USE_FILE_OFFSET64 \
 libgfxdr_la_LIBADD = $(top_builddir)/libglusterfs/src/libglusterfs.la \
                $(top_builddir)/rpc/rpc-lib/src/libgfrpc.la
 
+libgfxdr_la_LDFLAGS = -version-info $(LIBGFXDR_LT_VERSION)
+
 libgfxdr_la_SOURCES =  xdr-generic.c rpc-common-xdr.c \
                        glusterfs3-xdr.c \
                        cli1-xdr.c \

diff --git a/xlators/features/changelog/lib/src/Makefile.am b/xlators/features/changelog/lib/src/Makefile.am
index fbaaea628b7c2bf50661e71b95d44c7f6937e076..775f026cf72d8f69d319f6eeb40c3444164bb02b 100644 (file)
--- a/xlators/features/changelog/lib/src/Makefile.am
+++ b/xlators/features/changelog/lib/src/Makefile.am
@@ -9,7 +9,7 @@ libgfchangelog_la_CPPFLAGS = $(GF_CPPFLAGS) -D__USE_FILE_OFFSET64 -fpic \
 libgfchangelog_la_LIBADD = $(top_builddir)/libglusterfs/src/libglusterfs.la \
                        $(GF_GLUSTERFS_LIBS)
 
-libgfchangelog_la_LDFLAGS = $(GF_LDFLAGS)
+libgfchangelog_la_LDFLAGS = $(GF_LDFLAGS) -version-info $(LIBGFCHANGELOG_LT_VERSION)
 
 libgfchangelogdir = $(includedir)/glusterfs/gfchangelog
 lib_LTLIBRARIES = libgfchangelog.la