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

[Owen Taylor]

Carl Worth wrote:
> On Wed, 31 Aug 2005 09:47:51 -0400, Owen Taylor wrote:
> 
>>For example, something like:
>>
>>          int
>>          my_printf (void *my_object, const char *my_format, ...)
>>                __attribute__ ((format (printf, 2, 3)));
> 
> 
> Yes, something like that does have appeal. But I would still argue
> against putting something like that in a public cairo header file.

The particular example is picked as something that *only* has utility
when put into a public header file.

>>When hidden with appropriate macros and #ifdef __GNUC__.
> 
> 
> I think there's the rub. As soon as there's a bug in these macros,
> we start breaking the compilation of cairo-using programs, (which is
> worse than breaking the compilation of cairo itself).
 >
> And bugs do find their way into these checks. For example:
> 
> 	https://bugs.freedesktop.org/show_bug.cgi?id=4120

I don't think this is typical. And stuff that is *only* compile time
doesn't have to appear in the public headers. The public header
would have something like:

#ifndef CAIRO_DECLARE
#define CAIRO_DECLARE(r) r
#endif

>>The whole idea of using generated header files introduces a disturbing
>>degree of fragility into the build system. Speaking from experience,
>>build fragility is bad: it wastes time, it keeps people from getting
>>the software built, it discourages contributions; you can't hack on
>>a project unless you can build it from source. Give me a nice solid
>>segfault any day.
> 
> 
> I agree on the general "build fragility is bad" point. And that's
> exactly why I don't want a lot of #ifdefs in cairo's public header
> files. Pushing fragility out onto users of cairo is much worse than
> absorbing it within the build of cairo itself.

To me, the difference between "fragile" and "buggy" is that things
that are buggy can be fixed, and the bugs don't come back. Fragile
things break over and over again. (libtool linking against the
wrong copy of GLib when people try to build Pango is fragility...)

I don't see a block of platform-specific defines as being likely
to be fragile in this sense. Especially since we aren't really
talking about anything complex like __attribute__((visibility())).
We're talking about doing things on a per-platform basis.

On the other hand, unless we can everybody marching exactly in step
for the build system, solutions that depend upon extra steps in
the build system are going to be repeated problems. And solutions
that depend on the ordering of compile lines are historically
extremely fragile to libtool and automake version differences.
("We'll stick -I . at the beginnning to be helpful...")

>>It should also be pointed out that the primary audience we are trying
>>to address with this are people who *aren't* using cairo's standard
>>build system: they are people who are integrating cairo into the Mozilla
>>build  system, creating project files for MSVC, hand-crafting Makefiles
>>for OpenWatcom... so hiding behind a tested set of rules in a
>>Makefile.am isn't satisfactory.
> 
> 
> There's a legitimate concern here, certainly. But I'm not sure I'm
> drawing the same conclusion from it that you are.
> 
> One of the benefits I mentioned in the header-munging proposal was
> that the sed-magic would be run by all parties, whether or not any
> annotations were necessary. So, we could have better testing with this
> approach than one in which only a small subset of people compiling
> cairo do some header-file processing, (as is the case with the current
> cairo.def rule).

With decorated headers, we could do the same thing as the mozilla
people and use -fvisibility=hidden on modern GCC. While that's
specific to quite recent versions of GCC, it is something that many
of the core developers would see, and thus would see if the decorations
were wrong.

> As for the fact that some people are using other build systems. We
> can't prevent that, but well-tested pieces of Makefile rules could
> still be used elsewhere, (or even placed in scripts external to the
> Makefiles if that would help).
> 
> The other thing we can do is to try to improve our build system to
> eliminate some reasons that people avoid it, (though I don't expect to
> ever be entirely successful on that front).
> 
> 
>>Having two separate copies of the header in different directories with
>>the same name, sounds like a recipe for all sorts of wonderfully
>>difficult to debug build problems.
> 
> 
> I agree it's not a perfect solution, but it's what I've been able to
> come up with so far.

To some extent, this whole thing strikes me as a solution in search of a 
problem; the human eye is pretty good at stripping out excess noise
when it is consistently formatted excess noise. We are not adding 
hundreds of functions a week to cairo.h.

In the end, virtually all libraries that are widely used cross-platform
do decorate their headers. libxml, FreeType, apr, libpng, zlib,
so forth and so on. We get away with not decorating the GTK+ headers,
but I don't think anybody would consider the GTK+ stack simple to
get building on Windows, especially when not using automake.

>>If header cleanliness is a primary consideration, then there is an
>>argument for not trying to address these problems at all; .defs
>>files do work on Windows; OS/2 is a marginal platform these days.
>>But if you are going to address the problem, there is a stronger
>>argument for addressing them in a way that “just works” — and I'm
>>not convinced that a header-munging scheme is going to just work. 
> 
> I think I replied to this in more detail already in my reply to John
> Ellson down-thread.
> 
> We do have a start at a .def approach in the tree, but it was not
> getting pick-up from some Mozilla people who started proposing more
> header-file decoration. I'm just trying to find a solution that
> everyone is willing to live with.

What I was hearing from the Mozilla people was not "we dislike .defs
files" but "we want this to be the same as all the other pieces
of code that we deal with, so we can just drop it into our build
system". I don't think adding sed scripts to the build process is
going to achieve that.

Regards,
						Owen