Re: GDB's #include file policy

Re: GDB's #include file policy

[Andrew Cagney]

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

Re: GDB's #include file policy

[Eli Zaretskii]

On Wed, 14 Mar 2001, Andrew Cagney wrote:

> Several recent patches have prompted the question of what guidelines, if
> any, are there for GDB and its include files.
> 
> I think the short answer is that it hasn't had one and people have
> simply done what was necessary to keep it building.  I'd like to tighten
> this, just a little, so that people don't need to guess what goes where
> so here goes...

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.

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

The above enum is required for any header which declares prototypes of 
functions that deal with watchpoints.

After trying several solutions (which didn't work in interesting
ways), I finally gave up after I noticed that all the other files
which needed that simply cheated and declared the argument as an int
instead.

I think such cheats isn't the way we want GDB code to be written.
Perhaps someone could make basic data types defined by breakpoint.h
more accessible.

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

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

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.

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

> "tm.h" and "xm.h" are definitly on the way out.
> "nm.h" is probably heading the same way.

What will replace them?

GDB's #include file policy

[Andrew Cagney]

(or lack there off :-)

Hello,

Several recent patches have prompted the question of what guidelines, if
any, are there for GDB and its include files.

I think the short answer is that it hasn't had one and people have
simply done what was necessary to keep it building.  I'd like to tighten
this, just a little, so that people don't need to guess what goes where
so here goes...

Every GDB file looks like:

	#include "defs.h"
	#include "<random-bits>"
	#include "<more-random-bits>"
	#include "<yet-more-random-bits>"

the random bits are randomly ordered vis:

	#include "regcache.h"
	#include <system-header.h>
	#include "regcache.h"

trying to do otherwize would likely break things on some target.


"defs.h" contains all the basic declarations including key types
(LONGEST) and some very standard includes.  It also sucks in "config.h",
"bfd.h", "tm.h", "xm.h" and "nm.h".  For the moment it sucks in
"gdbarch.h" and a few other headers as well.  Header files should assume
that "defs.h" has already been included.

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.  This includes "tm.h" (until they are deleted).  This includes
functions in macros (until they are deleted also :-).

GDB has wrapper system headers (eg "gdb_wait.h").  Where added, they
should try to use POSIX or ISO-C as guidelines.  No real need to
introduce them until needed.

(Now the tricky bit) GDB headers should try to avoid sucking in system
header files.  The exceptions are "defs.h" and "gdb_*.h".  Probably also
"xm.h", "nm.h" and "terminal.h". 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.

"tm.h" and "xm.h" are definitly on the way out.
"nm.h" is probably heading the same way.

Hopefully this is sufficiently vague and waffly for no one to even
notice.

	Andrew