172 lines
6.3 KiB
Plaintext
172 lines
6.3 KiB
Plaintext
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.
|
|
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
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 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:
|
|
|
|
src/include/storage/s_lock.h and src/include/port/atomics/ are excluded
|
|
because they contain assembly code that pgindent tends to mess up.
|
|
|
|
src/backend/utils/fmgrtab.c is excluded because it confuses pgindent
|
|
and it's a derived file anyway.
|
|
|
|
src/interfaces/ecpg/test/expected/ is excluded to avoid breaking the ecpg
|
|
regression tests, since what ecpg generates is not necessarily formatted
|
|
as pgindent would do it. (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 the expected files may need to be updated to match.)
|
|
|
|
src/include/snowball/libstemmer/ and src/backend/snowball/libstemmer/
|
|
are excluded because those files are imported from an external project,
|
|
not maintained locally, and are machine-generated anyway. Likewise for
|
|
plperl/ppport.h.
|
|
|
|
src/include/jit/llvmjit.h is excluded because it contains C++ constructs
|
|
that confuse pgindent.
|
|
|
|
src/backend/utils/probes.h and its alias src/include/utils/probes.h
|
|
are excluded because that file is machine-generated by code not under
|
|
our control, and some versions of dtrace build files that confuse
|
|
pgindent.
|
|
|
|
|
|
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.
|