Adding upstream version 14.5.upstream/14.5upstream

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

1 files changed, 158 insertions, 0 deletions

diff --git a/src/tools/pgindent/README b/src/tools/pgindent/README
new file mode 100644
index 0000000..74412d2
--- /dev/null
+++ b/src/tools/pgindent/README
@@ -0,0 +1,158 @@
+pgindent'ing the PostgreSQL source tree
+=======================================
+
+We run this process at least once in each development cycle,
+to maintain uniform layout style in our C and Perl code.
+
+You might find this blog post interesting:
+http://adpgtech.blogspot.com/2015/05/running-pgindent-on-non-core-code-or.html
+
+
+PREREQUISITES:
+
+1) Install pg_bsd_indent in your PATH.  Fetch its source code with
+   git clone https://git.postgresql.org/git/pg_bsd_indent.git
+   then follow the directions in README.pg_bsd_indent therein.
+
+2) Install perltidy.  Please be sure it is version 20170521 (older and newer
+   versions make different formatting choices, and we want consistency).
+   You can get the correct version from
+   https://cpan.metacpan.org/authors/id/S/SH/SHANCOCK/
+   To install, follow the usual install process for a Perl module
+   ("man perlmodinstall" explains it).  Or, if you have cpan installed,
+   this should work:
+   cpan SHANCOCK/Perl-Tidy-20170521.tar.gz
+
+DOING THE INDENT RUN:
+
+1) Change directory to the top of the source tree.
+
+2) Download the latest typedef file from the buildfarm:
+
+	wget -O src/tools/pgindent/typedefs.list https://buildfarm.postgresql.org/cgi-bin/typedefs.pl
+
+   (See https://buildfarm.postgresql.org/cgi-bin/typedefs.pl?show_list for a full
+   list of typedef files, if you want to indent some back branch.)
+
+3) Run pgindent on the C files:
+
+	src/tools/pgindent/pgindent
+
+   If any files generate errors, restore their original versions with
+   "git checkout", and see below for cleanup ideas.
+
+4) Indent the Perl code using perltidy:
+
+	src/tools/pgindent/pgperltidy
+
+   If you want to use some perltidy version that's not in your PATH,
+   first set the PERLTIDY environment variable to point to it.
+
+5) Reformat the bootstrap catalog data files:
+
+	./configure     # "make" will not work in an unconfigured tree
+	cd src/include/catalog
+	make reformat-dat-files
+	cd ../../..
+
+VALIDATION:
+
+1) Check for any newly-created files using "git status"; there shouldn't
+   be any.  (pgindent leaves *.BAK files behind if it has trouble, while
+   perltidy leaves *.LOG files behind.)
+
+2) Do a full test build:
+
+	make -s clean
+	make -s all	# look for unexpected warnings, and errors of course
+	make check-world
+
+   Your configure switches should include at least --enable-tap-tests
+   or else much of the Perl code won't get exercised.
+   The ecpg regression tests may well fail due to pgindent's updates of
+   header files that get copied into ecpg output; if so, adjust the
+   expected-files to match.
+
+3) If you have the patience, it's worth eyeballing the "git diff" output
+   for any egregiously ugly changes.  See below for cleanup ideas.
+
+
+When you're done, "git commit" everything including the typedefs.list file
+you used.
+
+4) Add the newly created commits to the .git-blame-ignore-revs file so
+   that "git blame" ignores the commits (for anybody that has opted-in
+   to using the ignore file).
+
+Another "git commit" will be required for your ignore file changes.
+
+---------------------------------------------------------------------------
+
+Cleaning up in case of failure or ugly output
+---------------------------------------------
+
+If you don't like the results for any particular file, "git checkout"
+that file to undo the changes, patch the file as needed, then repeat
+the indent process.
+
+pgindent will reflow any comment block that's not at the left margin.
+If this messes up manual formatting that ought to be preserved, protect
+the comment block with some dashes:
+
+	/*----------
+	 * Text here will not be touched by pgindent.
+	 *----------
+	 */
+
+Odd spacing around typedef names might indicate an incomplete typedefs list.
+
+pgindent will mangle both declaration and definition of a C function whose
+name matches a typedef.  Currently the best workaround is to choose
+non-conflicting names.
+
+pgindent can get confused by #if sequences that look correct to the compiler
+but have mismatched braces/parentheses when considered as a whole.  Usually
+that looks pretty unreadable to humans too, so best practice is to rearrange
+the #if tests to avoid it.
+
+Sometimes, if pgindent or perltidy produces odd-looking output, it's because
+of minor bugs like extra commas.  Don't hesitate to clean that up while
+you're at it.
+
+---------------------------------------------------------------------------
+
+BSD indent
+----------
+
+We have standardized on FreeBSD's indent, and renamed it pg_bsd_indent.
+pg_bsd_indent does differ slightly from FreeBSD's version, mostly in
+being more easily portable to non-BSD platforms.  You can obtain it from
+https://git.postgresql.org/git/pg_bsd_indent.git
+
+GNU indent, version 2.2.6, has several problems, and is not recommended.
+These bugs become pretty major when you are doing >500k lines of code.
+If you don't believe me, take a directory and make a copy.  Run pgindent
+on the copy using GNU indent, and do a diff -r. You will see what I
+mean. GNU indent does some things better, but mangles too.  For details,
+see:
+
+	http://archives.postgresql.org/pgsql-hackers/2003-10/msg00374.php
+	http://archives.postgresql.org/pgsql-hackers/2011-04/msg01436.php
+
+---------------------------------------------------------------------------
+
+Which files are processed
+-------------------------
+
+The pgindent run processes (nearly) all PostgreSQL *.c and *.h files,
+but we currently exclude *.y and *.l files, as well as *.c and *.h files
+derived from *.y and *.l files.  Additional exceptions are listed
+in exclude_file_patterns; see the notes therein for rationale.
+
+Note that we do not exclude ecpg's header files from the run.  Some of them
+get copied verbatim into ecpg's output, meaning that ecpg's expected files
+may need to be updated to match.
+
+The perltidy run processes all *.pl and *.pm files, plus a few
+executable Perl scripts that are not named that way.  See the "find"
+rules in pgperltidy for details.