[cairo] Munging header files for export (and other) attributes

[Carl Worth]

Every once in a while, someone asks to decorate cairo.h with some sort
of per-function attribute. Something along the lines of:

	CAIRO_PUBLIC(cairo_t *)
	cairo_create (cairo_surface_t *target);

I have readability objections to the above, (I've also proposed hacks
to hide the worst of those), that I won't bother repeating here.

Beyond the ugliness, another problem with having attributes like this
is the maintenance problem of always remembering to include them when
adding new functions to the public header files, (and here my hacks to
hide the syntax actually make this problem worse).

But there's a more fundamental issue underlying each of the above
problems. For both consumers and maintainers of public header files,
export attributes are pure noise since there are no non-exported
functions in any of these files.

Additionally, I believe that most of the these attributes need to be
seen only by the compiler when compiling cairo itself. Much less
frequently there are attributes that need to be seen when compiling
software that uses cairo.

So, I'd like a solution that does not require maintainers to maintain
any attributes in the public header files, that presents the
attributes to the compiler when compiling cairo, and does not present
any attributes (or even ugly empty-defined macros) in installed header
files when not needed.

Since we have a very strict structure for our header files, this
should be very easy to automate. In fact, here's a script that takes
any public header file as they now exist and decorates each function
type with both CAIRO_PRE_DECL before the function return type and
CAIRO_POST_DECL after the function return type:

    sed -n -e '/^cairo.*(/ {x;s/\(.*\)/CAIRO_PRE_DECL \1 CAIRO_POST_DECL/;p;d}' \
           -e '{x;p}'

This script just expects to be fed a header file on stdin and it
produces a munged header file on stdout.

I think we should be able to use this script as part of a good
solution that meets my criteria above. One option would be to make the
internal header files #include an appropriate sed-modified version of
the header files, under Makefile control, (but with the munged files
likely not under revision control). Another option would be to make
the build process temporarily replace the header files with their
sed-modified versions and then restore them afterwards (so that we
don't commit modified versions to CVS). An additional possibility is
to make the "make install" process do some sed modification for the
platforms that really do require some attributes to appear in
installed public header files.

Of course, another piece of the solution is the platform-specific
identification of what these CAIRO_PRE_DECL and CAIRO_POST_DECL
strings should actually be. I'm sure that interested parties of
relevant platforms can supply the correct strings easily enough.

One advantage of this approach to the problem is that even if the
platform used by most cairo maintainers doesn't require any
attributes, it could be going through the same sed-script
modification. So the mechanics of this process would get continuous
testing, (unlike, say, the cairo.def approach already in CVS which has
a similar sed script that is only executed on a particular platform).

Anyone, there's a starting point for anyone that wants to propose a
more complete solution.

-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.freedesktop.org/archives/cairo/attachments/20050830/389b182c/attachment.pgp