From mboxrd@z Thu Jan  1 00:00:00 1970
From: Andrew Cagney <ac131313@cygnus.com>
To: GDB Discussion <gdb@sources.redhat.com>
Subject: GDB's #include file policy
Date: Wed, 21 Mar 2001 15:59:00 -0000
Message-id: <3AB00410.324AB111@cygnus.com>
X-SW-Source: 2001-03/msg00110.html

(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