113 lines
4.1 KiB
Plaintext
113 lines
4.1 KiB
Plaintext
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.
|
|
|
|
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
|
|
|
|
|
|
headerscheck
|
|
============
|
|
|
|
This script can be run to verify that all Postgres include files meet
|
|
the project convention that they will compile "standalone", that is
|
|
with no prerequisite headers other than postgres.h (or postgres_fe.h
|
|
or c.h, as appropriate).
|
|
|
|
A small number of header files are exempted from this requirement,
|
|
and are skipped by the headerscheck script.
|
|
|
|
The easy way to run the script is to say "make -s headerscheck" in
|
|
the top-level build directory after completing a build. You should
|
|
have included "--with-perl --with-python" in your configure options,
|
|
else you're likely to get errors about related headers not being found.
|
|
|
|
A limitation of the current script is that it doesn't know exactly which
|
|
headers are for frontend or backend; when in doubt it uses postgres.h as
|
|
prerequisite, even if postgres_fe.h or c.h would be more appropriate.
|
|
Also note that the contents of macros are not checked; this is intentional.
|
|
|
|
|
|
headerscheck --cplusplus
|
|
========================
|
|
|
|
The headerscheck in --cplusplus mode can be run to verify that all
|
|
Postgres include files meet the project convention that they will
|
|
compile as C++ code. Although the project's coding language is C,
|
|
some people write extensions in C++, so it's helpful for include files
|
|
to be C++-clean.
|
|
|
|
A small number of header files are exempted from this requirement,
|
|
and are skipped by the script in the --cplusplus mode.
|
|
|
|
The easy way to run the script is to say "make -s cpluspluscheck" in
|
|
the top-level build directory after completing a build. You should
|
|
have included "--with-perl --with-python" in your configure options,
|
|
else you're likely to get errors about related headers not being found.
|
|
|
|
If you are using a non-g++-compatible C++ compiler, you may need to
|
|
override the script's CXXFLAGS setting by setting a suitable environment
|
|
value.
|
|
|
|
A limitation of the current script is that it doesn't know exactly which
|
|
headers are for frontend or backend; when in doubt it uses postgres.h as
|
|
prerequisite, even if postgres_fe.h or c.h would be more appropriate.
|
|
Also note that the contents of macros are not checked; this is intentional.
|