src/tools/pginclude/README

   1 $PostgreSQL$
   2
   3 pginclude
   4 =========
   5
   6 These utilities help clean up #include file usage.  They should be run
   7 in this order so that the include files have the proper includes before
   8 the C files are tested.
   9
  10 pgfixinclude    change #include's to <> or ""
  11
  12 pgcompinclude [-v]
  13                 report which #include files can not compile on their own
  14
  15 pgrminclude [-v]
  16                 remove extra #include's
  17
  18 pgcheckdefines
  19                 check for #ifdef tests on symbols defined in files that
  20                 weren't included --- this is a necessary sanity check on
  21                 pgrminclude
  22
  23 pgdefine        create macro calls for all defines in the file (used by
  24                 the above routines)
  25
  26 It is also a good idea to sort the pg-specific include files in
  27 alphabetic order.  This is best done with a text editor. Typical usage
  28 order would be:
  29
  30         pgfixinclude
  31         sort include references
  32         run multiple times:
  33                 pgcompinclude
  34                 pgrminclude /src/include
  35         pgrminclude /
  36         pgcheckdefines
  37
  38 There is a complexity when modifying /src/include.  If include file 1
  39 includes file 2, and file 2 includes file 3, then when file 1 is
  40 processed, it needs only file 2, not file 3.  However, if later, include
  41 file 2 is processed, and file 3 is not needed by file 2 and is removed,
  42 file 1 might then need to include file 3.  For this reason, the
  43 pgcompinclude and pgrminclude /src/include steps must be run several
  44 times until all includes compile cleanly.
  45
  46 Also, tests should be done with configure settings of --enable-cassert
  47 and EXEC_BACKEND on and off.  It is also wise to test a WIN32 compile.