how to make two library versions coexist

[Havoc Pennington <hp redhat com>]

Hi,

I merged my notes with Ramiro's notes and made this short document on
how to fix libraries to live in parallel.

Havoc


Parallel library installation, 
or,
How to make two versions of a library coexist nicely so that users 
and developers can use both of them at once
===

Short answer: rename all files to include the version number.

Long answer:

 - rename the library to include its version number.
   So replace libgtk.la with libgtk-1.3.la or whatever.
 
 - all headers of BOTH the old and the new versions must be 
   in a subdirectory of includedir. So:

      includedir/eel1/eel/foo.h
      includedir/eel2/eel/foo.h

   #include <eel/foo.h>

   This may require a re-release of eel1 to fix, but it has to be
   fixed, or people including eel/foo.h will get the old headers.

   As long as you're using pkg-config or have a foo-config script, 
   moving the headers in this way shouldn't break anything for 
   people using that script.

 - if you have executables or data files, rename them or the directory
   they are inside.

 - change your .pc files or -config scripts to contain 
   -I includedir/eel2, and the new library name.

   DO NOT include -I includedir in the cflags the -config script
   outputs.

 - while we're mentioning -config scripts or .pc files, rename those
   too; so you'd use "pkg-config --cflags gtk+-2.0" for GTK+ 2
   and "pkg-config --cflags gtk+" for GTK+ 1, for example.
   Or gtk-config and gtk-config-2. And so on.

   If you're willing to use pkg-config, as you should be, 
   of course you can just nuke the -config script, and be sure
   your pkg-config module name includes the library version.

   Nuke/rename fooConf.sh and foo.m4 as well, if applicable.

 - docs need installing to a versioned directory also, of course, 
   a special case of data files.

 - change the gettext package name, otherwise the .mo files clobber
   each other.

 - make sure fooConf.sh.in, foo.m4 and foo-config.in are retired from the
   GNOME2 version of the library since its all pkg-config based.

 - you have to change any spec file or debian/ dir that exists to
   reflect all the new names.

 - check all Makefiles for hardcoded paths that have changed. 
   For example if your makefile contains datadir/foo, change to 
   datadir/foo2, etc.

 - naming schemes for renaming directories, the following have been
   used in the past:

    gconf - $prefix/include/gconf/{1,2}
    gtk   - $prefix/include/{gtk-2.0, gtk-1.2}
    eel   - $prefix/include/{eel-1,eel-2}

   The gconf scheme is kind of annoying IMO; the eel/gtk schemes 
   both seem fine to me.
   
 - if you have a daemon or shared data that both versions of the 
   library need to use, your life is more challenging; 
   for example, liboaf and libgconf are basically interfaces to 
   daemons. So at that point you have to handle the case where
   two different library versions talk to the same daemon.
   
   This has to be handled on a case-by-case basis. Just be sure
   you have a plan to handle it. Remember that there may be 
   apps using both versions of the lib active simultaneously.

Motivation
===

The reason this is necessary is because it isn't feasible to port all
apps to a widely-deployed library in one go. Say I am a user, and half
the apps out there require libfoo version 1, and half require libfoo
version 2; then I have to choose one set of apps, I can't have both, 
if the two libfoo versions have files in common.

Of course if libfoo 1 and 2 are binary compatible this isn't
necessary. This document is just about binary incompatible versions.