Re: GIO API review

[Michael Natterer <mitch imendio com>]

Alexander Larsson wrote:
> On Tue, 2007-12-11 at 17:48 +0100, Michael Natterer wrote: 
> > Hey everybody,
> >
> > We've been doing a GIO API review in the last couple of days and
> > here is the list of comments and issues we've come up with:
> >
> >
> > General:
> > ========
> >
> > It seems GIO allows individual files to be included, this should be
> > avoided like gobject does it:
> >
> > #if !defined (__GLIB_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
> > #error "Only <gio.h> can be included directly."
> > #endif
>
> Why? I know gobject does this, but I never understood why. It seems to
> just make build times longer.

Because otherwise you get into the very same typedef and include mess
we have in glib and gtk+. It makes it *very* hard to change anything
type related in the future. Any addition of a new function that happens
to use a new type which was not used in that header before might work
fine for the library's build itdelf, but might break the build of
applications that include whatever combination of headers.

Clear structure of headers and types should never be traded for compile
time, we also keep distinct things in distinct .c files. Why would we
scatter our typedefs across our libraries, or keep certain includes in
headers forever?

Allowing single library headers to be included just adds one more
completely unneccessary layer of compatibility that needs to be
preserved by all means as long as we guarantee source compatibility.

*Please* let's at least get rid of that compatibility mess by simply
not creating it in the first place.

Also, if you have a common header for your library, you can easily
split headers later if it turns out to be neccessary.

I would even argue that it makes most sense to keep all opaque typedefs
in one single file and include that from "gio.h" and from each source
file within GIO. This way you can avoid including any headers from
headers at all and it makes things so *very* much easier to maintain.
We changed all of GIMP to this policy a few years back and never had
a single (!!!) problem related to includes ever since.

Deploying such a policy makes it completely clear where the opaque
typedefs are: they are always in giotypes.h. There would be no need
to have the typedef for GMount in gfile.h and have a comment like this:

/* GMount typedef is in gfile.h due to include order issues */

in gmount.h, because there would be *no* include order issues.

(will follow up on the rest in another mail)

ciao,
--mitch