Adding upstream version 15.4.upstream/15.4upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 103 insertions, 0 deletions

diff --git a/src/tools/pginclude/README b/src/tools/pginclude/README
new file mode 100644
index 0000000..49eb4b6
--- /dev/null
+++ b/src/tools/pginclude/README
@@ -0,0 +1,103 @@
+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
+
+
+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 which headers
+are for frontend or backend, so it tests everything with postgres.h
+as prerequisite, even if postgres_fe.h would be more appropriate.  Also
+note that the contents of macros are not checked; this is intentional.
+
+
+cpluspluscheck
+==============
+
+This script 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 cpluspluscheck script.
+
+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 which headers
+are for frontend or backend, so it tests everything with postgres.h
+as prerequisite, even if postgres_fe.h would be more appropriate.  Also
+note that the contents of macros are not checked; this is intentional.