DBus GLib API

[Thiago Macieira]

Rob Taylor wrote:
>Can anyone with a bit more library maintenance experience give me some
>advice on the best way forward? I don't want to just ignore the ABI
>issue, given the rapidly growing number of components depending on
>dbus-glib. Is the best thing to try and maintain ABI going forwards and
>deprecating symbols as needed? I'll also take a look at the main library
>users, if they're just using the mainloop integration perhaps
>Alexander's suggestion of splitting off a static library with just the
>mainloop integration would be a sensible option.

Our experience with forwards binary compatibility in Qt and KDE libraries 
is as follows:

1) design good APIs (duh :-> ). This specially includes the fact that you 
shouldn't do something just because you can: do it because your API's 
users will need it. I know this came back to bit me in the *** in my old 
APIs...

The rule of the 80/20 and 90/10 applies here.

2) expose as little as possible of your underlying structure. That is, 
except in special cases where speed is an issue, avoid inline methods and 
avoid placing your class's (structure's) contents in the public header 
files. Instead, use opaque structures.

In the case of QtDBus, it was designed so that no libdbus header is ever 
included nor are any of the libdbus structures ever exposed to the user. 
There's only one class which is not opaque, except for the template one. 
I believe that to be an error on my part, but there are still no inlined 
methods (the members are private).

3) never, ever remove an existing function. Instead, deprecate them.

4) in case of public, generated structures, make sure you leave room for 
extension and add a version number. The two things can be one and the 
same: you can design your structures to start with its size. If you 
decide later you need more data, increase the size, deprecate the old 
fields and add new ones.

There's a lot more information on the web, but this is what I thought 
might be useful to you.

-- 
  Thiago Macieira  -  thiago (AT) macieira.info - thiago (AT) kde.org
    PGP/GPG: 0x6EF45358; fingerprint:
    E067 918B B660 DBD1 105C  966C 33F5 F005 6EF4 5358
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/dbus/attachments/20070214/62092716/attachment.pgp