[cairo] "export" annotations on public APIs

[Hans Breuer]

On 10.05.2005 22:08, Carl Worth wrote:
 > On Thu, 21 Apr 2005 15:59:12 +1200, Robert O'Callahan wrote:
 >
 >>Integrating Cairo into Mozilla, we've run into a problem building Cairo as a
 >>shared library --- there are no annotations to indicate which functions
 >>should be exported from a shared library, when building on a platform that
 >>doesn't export all symbols by default.
 >
 >
 > We have gone through the complementary effort and annotated each
 > function that should not be exported with "cairo_private", (though we
 > might not have 100% of the functions tagged at the moment). Could
 > those annotations be adequate for your use?
 >
Not really. There are basically three forms to export functions with the
'native' win32 compiler(s) :

__declspec(dllexport) : can be used for classes, functions, must be
	used for variables (which should not be exported at all in
	a clean designed library interface)

an export definition file : usually .def, like
		EXPORTS
			symbol
	can be used for function and with some extra effort (name mangling)
	for classes. Does not work for variables

on the compilers command line : (only useful for very few functions)
	cl $(CFLAGS) [...] /EXPORTS:symbol

For Cairo something similar to wht Gtk+ does seems appropriate. All
these libraries need to export system and feature dependent symbols.
So some source file conditionalizing these symbols to generate the
final export definitions via preprocessor seems appropriate.

This is how it was done in my recent (mostly ignored) win32 build
attempt. It is just at the top of the patch.

http://hans.breuer.org/gtk/cairo-2005-04-10-hb.diff

 >
 >>                                       This affects not only Win32, but now
 >>also gcc4 when we use "#pragma GCC visibility" to hide internal symbols.
 >>Would a patch that adds a CAIRO_EXPORT macro to all public functions (by
 >>default, defined to nothing) be looked upon favourably?
 >
AFAIK in Gtk+ the gtk.symbols file is also used with GCC below 4.0
to do PLT-reduction (eliminate overhead for unnecessary/unwanted
exports)

 >
 > One thing I really like about annotating the non-exported functions is
 > that the public header file does not get cluttered and, as such,
 > maintains quite good readability. I'd like to preserve that if we can.
 >
Sorry I fail to see why having the internal headers cluttered with
cairo_private is any better. For marking internal symbols the
underscore prefix convention should be enough ;-)

 > If annotations in the public header do prove unavoidable I might
 > suggest "cairo_public" as an annotation to maintain consistency with
 > our current cairo_private annotation. (But again, I'd prefer to only
 > have to mark the private functions).
 >
The definitions file approach - as described above - does not
clutter any source file and works quite well. [Gtk+ on win32 used
manually maintained .def for years, but now that these are
generated by corss platform .symbols files the win32 specific
maintenance became much less work ...

	Hans

-------- Hans "at" Breuer "dot" Org -----------
Tell me what you need, and I'll tell you how to
get along without it.                -- Dilbert