PARI library and versioning

[Bill Allombert <allomber@math.u-bordeaux.fr>]

Hello PARI developers,

I would like to summarize how PARI library versioning works now.

Since 2.1.0 is released, we maintain two releases, a stable and frozen 2.1
release and a development branch 2.2, unstable and hot :-)

All 2.1 libraries have the same soname, libpari.so.1.
All 2.1 libraries version are fully ABI and API compatible.
You use the "-lpari" linker flag to link against them.
Programs compiled with theses libraries with still work with new 2.1 versions
whether you recompile them or not. When the library is upgraded, your
dynamically linked program will use automatically the new one, and still
work, so you can safely remove older 2.1 releases.

CVS: Between CVS transaction, 2.1 CVS branch should be fully ABI and API
comptatible with other 2.1 versions, barring bugs in the CVS.

(Note that cvs does not support 'transaction'. These mean if I commit
changes in two files at the same time you update you tree you can get half of
the change and end up with a broken version).

GP2C: GP2C compiled for a 2.1 release or with --without-pari should work
equally well with all 2.1 releases. Compiled plug-ins should works
with all GP 2.1. 

---
For the development branch 2.2.x , things are differents.

Each 2.2.x has its own API and ABI.
2.2.x library soname is libpari-2.2.so.x.

*** You use the "-lpari-2.2" linker flag to link against 2.2 libs. ***

There is no guaranty that programs compiled with older 2.2.x will
compile with new 2.2.y (though it should usually work). There is 
*really* no guaranty (i.e. it should usually fail) that program dynamically 
linked against libpari-2.2.so.x. works with libpari-2.2.so.y. To avoid
upgrading PARI breaking your programm, things are arranged so that
several versions of the libraries can live together peacefully.
Dynamically linked programm against 2.2.x are set up to search for
libpari-2.2.so.x, so will not break if you install libpari-2.2.so.y, until
you remove libpari-2.2.so.x.
Staticaly linked programms are not affected by upgrade in either case.

CVS:
Each 2.2 CVS state has its own API and ABI, and there is no protection
with dynamic linking, so you are advised to compile statically 
programs linked against the CVS 2.2 version that you want to keep.
(Note: if you upgrade your libpari under a 'good' OS (Linux, Solaris, OSF),
this will not break running processes.) 

GP2C: gp2c need to be recompiled each time the API change, i.e each time
PARI 2.2 is upgraded. There is no guaranty plugin compiled against
old PARI 2.2 version will work with new one.

VERSIONING
If you need to compile your code with several PARI version which have distinct
API, you can use the (just in the CVS) symbol:

PARI_VERSION_CODE and PARI_VERSION

This is mean to be used as 

#if PARI_VERSION_CODE<PARI_VERSION(2.2.0)
/*2.1 and older API code*/
#elif PARI_VERSION_CODE<=PARI_VERSION(2.2.2)
/* code compatible with 2.2.0-2 APIs*/
#else 
/* code compatible with newer APIs.
#endif

GLOSSARY: (From The Free On-line Dictionary of Computing)

ABI:  Application Binary Interface

          <programming> (ABI) The interface by which an {application
          program} gains access to {operating system} and other
          services.  It should be possible to run the same compiled
          {binary} applications on any system with the right ABI.

API:  Application Program Interface

          <programming> (API, or "application programming interface")
          The interface (calling conventions) by which an {application
          program} accesses {operating system} and other services.  An
          API is defined at {source code} level and provides a level of
          {abstraction} between the application and the {kernel} (or
          other privileged utilities) to ensure the {portability} of the
          code.

          An API can also provide an interface between a {high level
          language} and lower level utilities and services which were
          written without consideration for the {calling conventions}
          supported by compiled languages.  In this case, the API's main
          task may be the translation of parameter lists from one format
          to another and the interpretation of {call-by-value} and
          {call-by-reference} arguments in one or both directions.

TODO:
Add this to the pari manual.

Bill.