Writing Shared Libraries, first draft

[Havoc Pennington]

On Fri, 2004-11-05 at 11:38 +0000, Scott James Remnant wrote:
> Libraries should only be parallel-installable across major version
> boundaries, and only then if the newer version doesn't entirely
> deprecate the former from a development POV.

I'd be careful with terms like "major version" - people can interpret
that sort of thing to mean whatever they want:
 - soname major
 - "an important new release"
 - the number on the left of the decimal point in the tarball name
 - ABI break
 - ABI addition

Parallel install should happen according to a very specific rule: when
an app asks for an interface by name, it should always get something
with the same interface and semantics it expected.

Interface can be a command line tool and its options, a bunch of C
symbols, a Java interface, a file format, anything that is provided by
one module to another module.

If the interface is no longer compatible, then the name used to refer to
it should change.

Names used to refer to an interface can include the .pc file name, the 
library name passed to the linker, the binary name, or whatever.

This potentially has nothing to do with the version number on the
tarball, etc.

> GTK+ is a good example of a library where the new major version doesn't
> entirely deprecate the former, you still want to develop applications
> that use GTK+ 1.x.

GTK 1.x is 100% deprecated and is officially a bad idea to use ;-)

> This is actually a rarer case than it seems, often you want to
> deliberately force people into always using the latest development
> version of your library ... in which case it makes more sense to make
> them hard to parallel install.

I think you have this backward, honestly.
I argue in http://ometer.com/parallel.html that parallel install speeds
up adoption of the new version, and I still think that's true.

If you don't have parallel install, adopting the new version can range
from pain in the ass to virtually impossible. And it will make a big
swampy mess in the process. All the distributions will do parallel
install anyway, because they have to, they'll just all do it
differently.

There is no reason to make people use a new version. If people like GTK+
1.x, then more power to them, masochism lives on. Not hurting the GTK+
developers any.

If you want people to use the new version, offer compelling reasons to
switch, and be sure it's easy to port.

> Header versioning isn't required ... if you correctly maintain backwards
> compatibility within a major version you don't need it.  Applications
> simply use whatever versions of library they require and check the
> headers declare them (or pkg-config knows the version is recent enough)
> in configure.ac

I agree with that.

> Structure size changes are actually far less of a problem than you make
> out.  Structures are almost never passed-by-value into a function, and
> rarely used-by-value in another structure.

My suggestion would be Only Opaque Objects Allowed. In all my new
libraries such as libwnck and libdbus, there basically aren't any struct
fields exposed in the headers, with maybe a couple of special cases.
This eliminates one of the largest reasons to break ABI and usually
results in an easier to use API anyhow.

> The exception, of course, is GTK+ which relies on being able to
> predictably embed structures inside each other.

GTK+ has the infrastructure now to make everything fully opaque, but
it's not considered worth the ABI break to change at this point.

Havoc