[cairo] Conditionally include debug functions with ENABLE_DEBUG_FUNCS

[BJörn Lindqvist]

On 10/18/07, Behdad Esfahbod <behdad at behdad.org> wrote:
> On Thu, 2007-10-18 at 17:13 -0400, BJörn Lindqvist wrote:
> > Hello,
> >
> > Here is a patch that introduces a ENABLE_DEBUG_FUNCS macro define. Its
> > purpose is to allow for debug stuff to be conditionally included in
> > Cairo proper. Things that must be exposed for testing to work, but
> > that should not be included in the final and really public API.
> >
> > An example is the cairo_boilerplate_xlib_surface_disable_render()
> > function. It is one of those functions that it is much easier to deal
> > with if it is inside Cairo rather than outside since it must mock
> > around with Cairo internals to work.
> >
> > Other debug functions than cairo_xlib_surface_disable_render() can be
> > added in the future.
>
> So, what's the justification for this?  Boilerplate functions used to be
> in libcairo and it took me two or three days of work to move them out to
> get to the clean state that it is currently.  Moving them back is just
> regressing.

My fault, I thought this problem had already been discussed,
sorry. Quick recap (you already know this), Cairo tries to put up a
fence around its implementation so that you are forced to rely on the
public API. The C language is pretty crappy when it comes to
encapsulation and only has two modes: everyone can use or no one can
use. Cairo has no public API for disabling Xrender, but if you really,
really want to use it anyway, and you can change the implementation,
then there are 3 options:

A. Add a cairo_xlib_surface_disable_render() function to the public
   API.
B. Cheat your way through the encapsulation using private headers.
C. Conditionally compile Cairo for code that uses
   cairo_xlib_surface_disable_render().

I prefer A, because that is the option you would have used in Java and
it puts the test suite on an equal footing with other 3rd party code
(where it should be). It is also easy to extend with
cairo_xlib_surface_disable_shm() and similar features. But I know that
is not what you want.

B is fragile because it relies on internals. It breaks if you happen
to include cairoint.h. For example, I tried to move the render_major
and render_minor attributes to the screen_info struct, but that
doesnt' work because the
cairo_boilerplate_xlib_surface_disable_render() doesn't know about the
cairo_xlib_screen_info_t struct. And it's hard to fix because
including cairo-xlib-private.h in cairo-boilerplate-xlib.c drags in
cairoint.h too.

So that leaves us with C as the lesser of the evils. But maybe there
is a better way to fix the problem?


-- 
mvh Björn