RPSL applies the standard library versioning approach that is available from 
the autotools.  Under this system, two types of versioning are maintained for 
a library module: release and shared. These are explained as follows:

Release version:  0.0.1  (major).(minor).(micro)
---------------------------------------------------------

Release refers to both interface and implementation and is a dotted 
triplet. In RPSL it is set by changing the first three numbers in the release 
line in the file rpslParams and re-running rpslSyncBuild and re-making 
the library. The compatibility of other libraries and executable modules is 
specified in their rpslParams pkg-config dependencies. These determine
the range of release versions for each library that are permissible to be 
included and linked against. 

Specifically, the compatibility is enforced prior to compile time by the 
pkg-config macro during configure. There will be an error message when running 
configure if the library release version requirements are not met by the first
instance of the library when searching PKG_CONFIG_PATH environment variable.  
The paths specified by the environment variable PKG_CONFIG_PATH are searched, in 
order, for the first instance of a pc file corresponding to the library name.  
Then the pc file is checked to see if the version meets the requirements.  If 
so, configure will proceed, if not, configure will stop with an error.  

Note: the test will be applied only once, to the first instance of the named
library in the PKG_CONFIG_PATH.

Because of magic in pkg-config, transitive dependencies are supported via the
"Requires:" line in the pc file. If execA<-libB<-libC then execA will know
check for the right version, and to link libC without its being in the 
rpslParams file of the executable explicitly. RPSL automatically populates the
"Requires:" items in the pc files.


Shared library version: 0:2:0  (current):(revision):(age)
---------------------------------------------------------

The shared version refers to interface compatibility in dynamic libraries (shared
objects).  Shared version control because it is nice to be able to update a 
dynamic library without changing the other libraries, relinking or updating the
executable.

In RPSL, it is set by changing the "shared" line in the rpslParams file, 
re-running rpslSyncBuild and re-making the library. The executable "remembers"
the shared version for each library that was linked when it was compiled. The 
compatibility is enforced at run time by the linker according to the following 
plan:

   current:   current interface exported
   revision:  the implementation number of the current interface (not used)
   age:       number of previous interfaces still supported 

If the executable was compiled with a library whose current interface is now 
older (smaller number) than current - age, then the executable will not 
run with the new library and complains with an error message.


Version specification and control
---------------------------------------------------------

Currently RPSL/autotools takes a release and shared version specification in
the rpslParams file, for example, consider

release = 4.5.6
shared = 9:0:6

This will install the following files

libname-4.5.so.3        -libname-4.5.so.3.6.0
libname.so              -libname-4.5.so.3.6.0
libname-4.5.so.3.6.0    (actual shared object)
libname.a               (statically linked object)
libname.la              (libtool helper script for dependency tracking, etc.)

The libtool version naming convention is as follows:

libname-4.5.so.3.6.0
        | |    | | |
        | |    | | |___revision of current interface
        | |    | |_____age (number of interfaces)
        | |    |______oldest interface supported
        | |_________minor release
        |_______major release


Summarizing what was said earlier:

The release version is specified by rpslParams.
The release version requirements of a dependent library are enforced at 
configure time by the pkg-config macro via the specification in the pc file.  
The shared version is specified by rpslParams.
The required shared version requirements by a dependent library or executable
are enforced by libtool and the linker at run time.


Working with more than one library version 
-------------------------------------------------------------------

There are at least two options for developing against libraries with 
different versions.  This is needed when a new version breaks the interface 
or functioning of a library, and some development or testing must continue 
with the old version until everything is updated for the new one.

One method is to build and install the old version to the group project tree 
and to develop the new version in the local user tree.  In order to include 
and link against the new version locally, the rpslParams specification in 
the new, user version must agree with the requirement in the rpslParams 
files of other modules that use it. Recall that the user tree is searched 
first for a pc file by pkg-config (if you set up RPSL as described), so it 
will use the new version if it exists locally.  To revert to the common version 
in the project or global sandbox, the new, local user version can be uninstalled
(make uninstall) locally.

Another method to have different versions co-exist in the same sandbox, one
at a time, is to put a tree of each version with separate names or directories
the same sandbox:

$RPSL_PROJ/
 build/
     libr1-old/   (version 0.0.1)
     libr1-new/   (version 1.0.0)

Then, running make uninstall in one, and make install in the other 
will switch the installed version for including and linking.

top