src/tools/pginclude/README

pginclude
=========

These utilities help clean up #include file usage.  They should be run
in this order so that the include files have the proper includes before
the C files are tested.

pgfixinclude	change #include's to <> or ""

pgcompinclude [-v]
		report which #include files can not compile on their own

pgrminclude [-v]
		remove extra #include's

pgcheckdefines
		check for #ifdef tests on symbols defined in files that
		weren't included --- this is a necessary sanity check on
		pgrminclude

pgdefine	create macro calls for all defines in the file (used by
		the above routines)

It is also a good idea to sort the pg-specific include files in
alphabetic order.  This is best done with a text editor. Typical usage
order would be:

	pgfixinclude
	sort include references
	run multiple times:
		pgcompinclude
		pgrminclude /src/include
	pgrminclude /
	pgcheckdefines

There is a complexity when modifying /src/include.  If include file 1
includes file 2, and file 2 includes file 3, then when file 1 is
processed, it needs only file 2, not file 3.  However, if later, include
file 2 is processed, and file 3 is not needed by file 2 and is removed,
file 1 might then need to include file 3.  For this reason, the
pgcompinclude and pgrminclude /src/include steps must be run several
times until all includes compile cleanly.

Also, tests should be done with configure settings of --enable-cassert
and EXEC_BACKEND on and off.  It is also wise to test a WIN32 compile.

Another tools that does a similar task is at:

	http://code.google.com/p/include-what-you-use/

An include file visualizer script is available at:

	http://archives.postgresql.org/pgsql-hackers/2011-09/msg00311.php