On numbers as part of library names

[Carl Worth]

On 07 Aug 2007 18:25:48 +0200, Soeren Sandmann wrote:
> >
> > I definitely don't see any advantage to starting off with a -1 as part
> > of the name.
>
> Do you see any disadvantages?

Yes, actually.

> The advantage is that if we have to break API, then two versions
> pixman-1 and pixman-2 can be installed in parallel. That way xorg and
> cairo could upgrade to a new version separately.

As Behdad mentioned, "pixman" and "pixman-2" could be installed in
parallel as well.

> Havoc has explained it here:
>
>         http://www106.pair.com/rhp/parallel.html

Sure, I'm quite familiar with this. And I totally agree that when
functionality changes, names have to change, or else we've just got
insanity.

But I do not accept that "having a version number in the library name
is just good practice" in general.

One thing that is just good practice is to use the same name for the
same thing as often as possible. We've been talking for a while now
that both cairo and the X server depend on "pixman" and today if you
try to compile a fresh checkout of cairo you can get a message that
says:

	configure: error: pixman >= 0.9.4 is required
	(http://xorg.freedesktop.org/releases/individual/lib/pixman-0.9.4.tar.gz)

Here, clearly, the name "pixman" is used again. But the actual
pkg-config name is now "pixman-1". And that inconsistency is
definitely a bad thing.

So if you really want to make the name of the library something other
than "pixman", then please use the same name as the pkg-config module
version, in error messages such as the above, and in the tar file as
well.

The harder part is to also to get people to start talking, (verbally,
in IRC, email etc.), about "pixman 1" where the number is really part
of the name. I think that's hard to do when the number isn't
distinguishing it from anything else, (contrast to "GTK 3" where
people _do_ actually use the number in verbal conversation, since it
serves a meaningful purpose).

And on that point, here's another argument against putting numbers
into library names, (and why I asked about plans). For cairo, I never
plan to make a "cairo 2" release. If at some point in the future we
find that we are so limited by the cairo API that we want to break
that compatibility, then I will encourage people to invent new
interfaces with an entirely new name, (that is, an entirely new
library). This still totally satisfies all the parallel installability
concerns that Havoc expressed, but it also does a lot more.

For one, an entirely new name means that there will be no conflicting
symbols, (since the new name will appear in all symbols), so there's
no problem with a single process linking against both the old and new
things.

Secondly, it avoids the problem of someone saying "project <foo>
requires cairo" and someone else getting frustrated to find that
project <foo> doesn't work with the "cairo 1" they have and they'll
need to get "cairo 2" instead. Yes, package management systems in
distributions solve a lot of this for packaged software, but not for
new, bleeding-edge stuff---which is where the first "cairo 2" users
would be. I imagine that most readers can recall times trying to use
something they though needed "perl" when it actually needed "perl 5"
or that needed "python" when it actually needed "python 2.4".

But finally, and most importantly, inventing an entirely new name
means that the proposed replacement need not be perfect. We could have
multiple "cairo replacements" be proposed, experimented with, and fail
without ever tarnishing the history or name of the cairo project
itself.

Interestingly, as GTK+ has contemplated an API-breaking "GTK+ 3"
release for a very long time, (which has been contentious and slow to
ever get moving), the conclusion recently reached was to start with
small experiments that do basically start from scratch. Look how
freeing it is to just invent a new name rather than try to feel
obligated to step into the shoes of GTK+ 2 and also do better, which
is the pressure you feel if you start with nothing but the name of
"GTK+ 3".

Now, the above lists some of my general feelings on library, (and
large project), naming. And I haven't even touched on things like
silent punctuation as part of names, like the '+' in "GTK+" or worse,
the "+-" in the pkg-config module of "gtk+-2.0". And notice that
there's a similar silent '-' in the current "pixman-1" name.

But, aside from these general issues, the case of pixman is quite
distinct from cairo and GTK+. Pixman is not intended to be a
general-purpose library. It's only intended to have two users, (cairo
and the X server), so a lot of the above can easily not apply. For
example, we don't expect people to be sharing cute little
pixman-requiring projects that might lead to frustrating dependency
issues. And the silent '-' can be typed once into each of the cairo
and xserver configure.ac files and then largely forgotten about.

So that's why I asked about a plan.

If we want to do one big round of fixing up pixman's API and then
freezing on that "forever" then let's just stick to a name of
"pixman". But if we plan to break the API left and right, then, sure,
let's come up with some other naming scheme, (but please let's try to
apply the naming scheme much more universally---including in
conversation: Imagine, "The upcoming cairo 1.6 release will depend on
pixman1 while xserver 1.4 will depend on pixman2").

> I definitely agree that a plan should be in place. Off the top of my
> head, here are some issues; there may be more:

Thanks for this list. I'd like to do my own review of the pixman API
in plenty of time before cairo 1.6. So I'll try to do it before the
end of August when we plan to make a cairo 1.5.2 development snapshot.

-Carl
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://lists.x.org/archives/xorg/attachments/20070807/91790c1e/attachment.pgp>