Re: GDB's #include file policy

[Andrew Cagney <ac131313 at cygnus dot com>]

Eli Zaretskii wrote:

> I think this should go into gdbint.texinfo.  If the text you've posted
> is all there is to it, I will convert it to Texinfo and add to the
> manual; if not, please tell what else we should have there.

This is the bit of the TODO file which reads:

   and most likely also:

       o         include conventions

I'll give it a week and then follow up with some real text.

> > Outside of "defs.h", GDB header files should try to be self contained
> > (struct foo * VS typedef ...).  If a header file uses typedefs from
> > another GDB header (but not defs.h) then that should really be dragged
> > in.
> 
> I bumped into one problem with the current headers which I was unable
> to solve easily: If you want to declare a prototype for a function
> which accepts an argument of the type `enum target_hw_bp_type', you need
> to include breakpoint.h, where that enum is defined.  However, including
> breakpoint.h is not for the faint of heart: it wants to pull in
> everybody and their dog, which triggers compiler warnings and other
> atrocities.

Ah, yes, that one.  It is like ``enum target_signal''.  In the past
those enums have ended up in defs.h :-/

> > (Now the tricky bit) GDB headers should try to avoid sucking in system
> > header files.
> 
> Why?  Unlike GDB headers, including more system headers doesn't really
> hurt, as it doesn't cause unnecessary recompilation.  And system
> headers are idempotent anyway.

As an example of what to _not_ do, the TUI currently causes "defs.h" to
suck in <curses.h>.  Trust me, that one is bad, really bad.

While system headers are _ment_ to be idempotent, my memory of them is
that they often are not :-( :-)

> The problem with this request is that you might need some definition,
> such as size_t, which you cannot have without a system header.

The thing is, I suspect that in general, this won't occure.

For instance, if someone added a generic (multiarch) interface to GDB
that took PID_T as a parameter (hence requiring gdbarch to pull in
<types.h>) I think it would be wrong.  The interface should instead be
using a non host specific type (something like TPID in this case)
defined in defs.h.

> If defs.h is supposed to take care of that, it might be trouble
> waiting to happen: someone changes defs.h some day, and then all kinds
> of platforms start breaking.

Yes.  Part of the autoconf philosophy appears to be to keep system
includes as localized as possible.

> > I think the pratical reality is that
> > either "defs.h" will have already dragged the header file in (<stdio.h>)
> > or that a .C rather than a .H file should be doing the include.
> 
> The latter possibility has a disadvantage of forcing specific order of
> header inclusion: you cannot safely include a GDB header before the
> system header which defines some of the stuff the GDB header uses.

An aside, that happens now.  Getting system header include order right
is a black art.  I'm trying to remember where I encountered it but I've
seen projects that were forced to move system includes out of .h's and
into carefully ordered .c's because different combinations ended up
clashing.  I think it had something to do with X11.

Any way, all I'm trying to say is that GDB by and large should be able
to avoid this whole can of worms since its header files mostly only
refer to GDB specific types and not system types.

> > "tm.h" and "xm.h" are definitly on the way out.
> > "nm.h" is probably heading the same way.
> 
> What will replace them?

xm.h is replaced by autoconf.
tm.h is replaced by the multi-arch framework.
nm.h is hopefully repaced by work by KevinB (solib) and others.

enjoy,

	Andrew