mirror of
https://github.com/postgres/postgres.git
synced 2026-06-11 01:30:11 -04:00
05d8dec690
Wrap the perltidy invocation into a shell script to reduce the risk of copy-and-paste errors. Include removal of *.bak files in the script, so they don't accidentally get committed. Improve the directions in the README file.
146 lines
5 KiB
Text
146 lines
5 KiB
Text
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 (see below for details).
|
|
|
|
2) Install entab (src/tools/entab/).
|
|
|
|
3) Install perltidy. Please be sure it is v20090616 (older and newer
|
|
versions make different formatting choices, and we want consistency).
|
|
|
|
DOING THE INDENT RUN:
|
|
|
|
1) Change directory to the top of the source tree.
|
|
|
|
2) Remove all derived files (pgindent has trouble with flex files, and it
|
|
would be pointless to run it on them anyway):
|
|
|
|
make maintainer-clean
|
|
Or:
|
|
git clean -fdx
|
|
|
|
3) Download the latest typedef file from the buildfarm:
|
|
|
|
wget -O src/tools/pgindent/typedefs.list http://buildfarm.postgresql.org/cgi-bin/typedefs.pl
|
|
|
|
(See http://www.pgbuildfarm.org/cgi-bin/typedefs.pl?show_list for a full
|
|
list of typedef files, if you want to indent some back branch.)
|
|
|
|
4) 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.
|
|
|
|
5) 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.
|
|
|
|
VALIDATION:
|
|
|
|
1) Check for any newly-created files using "git status"; there shouldn't
|
|
be any. (perltidy tends to leave *.LOG files behind if it has trouble.)
|
|
|
|
2) Do a full test build:
|
|
|
|
./configure ...
|
|
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.
|
|
|
|
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 NetBSD's indent, and renamed it pg_bsd_indent.
|
|
We have fixed a few bugs which requre the NetBSD source to be patched
|
|
with indent.bsd.patch patch. A fully patched version is available at
|
|
ftp://ftp.postgresql.org/pub/dev.
|
|
|
|
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. 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/interfaces/ecpg/test/expected/ is excluded to avoid breaking the ecpg
|
|
regression tests. Several *.h files are included in regression output so
|
|
should not be changed.
|
|
|
|
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.
|
|
|
|
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.
|