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

[Behdad Esfahbod]

Hi Carl,

I like the sed approach.  I suggest moving public headers out of
src/, in another directory like include/ for example, and then
have Makefiles generate modified headers into src/.  The modified
headrs will be shipped in the tarball, such that sed is not
needed as long as the master includes are not modified.  As a
last resort, -I$(top_srcdir)/src will be appended to the CFLAGS
for src/ such that if modified header files are not available,
original ones will be used.

How's that?

behdad


On Tue, 30 Aug 2005, Carl Worth wrote:

> 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
>

--behdad
http://behdad.org/