Header namespacing

[Havoc Pennington]

Hi,

On Wed, 2005-12-14 at 21:21 +0100, Kevin Krammer wrote:
> I am currently working on a Qt3 backport of the Qt4 DBUS bindings.
> 
> In a full DBUS install this would currently result in one Qt binding 
> overwriting the other's headers.
> 
> How do other binding developers plan to handle the version change situation?
> 
> Include the version number in the filename, e.g.
> dbus-1.0/dbus/q3dbus.h and dbus-1.0/dbus/q4dbus.h?
> 
> Or in a subdirectory of the top level dbus include directory e.g.
> dbus-1.0/qt3/dbus/qdbus.h and dbus-1.0/qt4/dbus/qdbus.h?
> 
> Or with the dbus/ directory, e.g
> dbus-1.0/dbus/qt3/qdbus.h and dbus-1.0/dbus/qt4/qdbus.h?
> 

http://ometer.com/parallel.html may be helpful for understanding what's
up with the "dbus-1.0/dbus/dbus.h" header naming.

I would suggest that if you can imagine using both Qt bindings in the
same program, you want to allow:
 "pkg-config --libs dbus-qt3 dbus-qt4"
and also:
  #include <dbus/qt3/qdbus.h>
  #include <dbus/qt4/qdbus.h>

But if one program is always going to use one or the other, there's no
point making people sed-job their headers on upgrade; then you probably
just want:
  #include <dbus/qt/qdbus.h>
and have the programmer use pkg-config (or some equivalent) to select
the right header, by getting the right -I flags. In this case you will
probably need to install to a different directory than dbus-1.0, maybe 
you want both:
  -I/usr/include/dbus-1.0-qt3
and
  -I/usr/include/dbus-1.0-qt4

and then inside those have the dbus/qt/qdbus.h.

Anyway, I think of the -I directory as specifying the library that you
want (it should change whenever the library name in /usr/lib changes).
The programmer would set this up in configure.in.

Then I think of the #include name as the "API" you want (i.e. possibly
similar APIs are implemented by different versions of the library). The
programmer would specify this in the code file where they use the API.

It's OK if two slightly incompatible libraries use the same #include
name, as long as there's no scenario where people would want to use both
of those libs at once. So for example both GTK+ 1.2 and 2.0 use
<gtk/gtk.h>. 1.2 and 2.0 are not compatible, but it's just not possible
to use both of them at once, and gtk/gtk.h will always point to the one
you asked for in configure.in.

Havoc