src/tools/pginclude/README

NOTE: headerscheck and headerscheck --cplusplus are in current use,

and any problems they find should generally get fixed. The other

scripts in this directory have not been used in some time, and have

issues. pgrminclude in particular has a history of creating more

problems than it fixes. Be very wary of applying their results

blindly.

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.

pgfixincludechange #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

pgdefinecreate 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

headerscheck

============