Writing Shared Libraries, first draft

[Matthias Clasen]

On Thu, 2004-11-04 at 15:34, Mike Hearn wrote:
> Hi guys,
> 
> The GNOME HIG has proven useful for increasing the usability of open
> source applications, even for apps that aren't actually GNOME programs.
> By providing best practice guidance and training materials for
> developers, it helps our community develop better software.
> 
> I thought I'd try writing an equivalent for library developers. This
> document gathers together generally accepted best practices and sticks
> them all in one document complete with examples. Here it is:
> 
> http://navi.cx/~mike/writing-shared-libraries.html
> 
> There are a few controversial points in it (well duh, the HIG is/was
> controversial too :)
> 
> - The parts on backwards compatibility and semantic interfaces may prove
>   new to some people. Like any guide, you are free to ignore any part if
>   you can justify it :)
> - The restricted form of symbol versioning described is not widely used
>   so it's hardly a best practice, but is generally accepted as being a
>   good plan on platforms that support it
> - Some people don't like the idea that software/package version should
>   equal interface version. I do not know why.
> - As far as I know, no library today actually implements all of the 
>   recommendations given here so you can't really call it a best
>   practices document. Oh well :)
> 
> I'd appreciate comments. I have already been told the part on applying
> symbol versions is a bit confusing, I will try and clarify it later.

I think you overemphasize the usefulness of symbol versioning.
It is much better to avoid the need for different symbol versions.

You could maybe add something about avoiding accidentally exporting
symbols, cf the abi checking we recently introduced in glib and gtk+.

Maybe you also want to mention that it is a good idea to avoid
unnecessary PLT entries, and point out some ways of achieving that
(or just point to Ulrichs paper).

Does the scope of your document include dos/don'ts for making sure
the api is language binding friendly ?

Matthias