src/tools/pgindent/README

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.