1pgindent'ing the PostgreSQL source tree 2======================================= 3 4We run this process at least once in each development cycle, 5to maintain uniform layout style in our C and Perl code. 6 7You might find this blog post interesting: 8http://adpgtech.blogspot.com/2015/05/running-pgindent-on-non-core-code-or.html 9 10 11PREREQUISITES: 12 131) Install pg_bsd_indent in your PATH. Fetch its source code with 14 git clone https://git.postgresql.org/git/pg_bsd_indent.git 15 then follow the directions in README.pg_bsd_indent therein. 16 172) Install perltidy. Please be sure it is v20090616 (older and newer 18 versions make different formatting choices, and we want consistency). See 19 https://sourceforge.net/projects/perltidy/files/perltidy/perltidy-20090616/ 20 21DOING THE INDENT RUN: 22 231) Change directory to the top of the source tree. 24 252) Download the latest typedef file from the buildfarm: 26 27 wget -O src/tools/pgindent/typedefs.list https://buildfarm.postgresql.org/cgi-bin/typedefs.pl 28 29 (See https://www.pgbuildfarm.org/cgi-bin/typedefs.pl?show_list for a full 30 list of typedef files, if you want to indent some back branch.) 31 323) Run pgindent on the C files: 33 34 src/tools/pgindent/pgindent 35 36 If any files generate errors, restore their original versions with 37 "git checkout", and see below for cleanup ideas. 38 394) Indent the Perl code using perltidy: 40 41 src/tools/pgindent/pgperltidy 42 43 If you want to use some perltidy version that's not in your PATH, 44 first set the PERLTIDY environment variable to point to it. 45 46VALIDATION: 47 481) Check for any newly-created files using "git status"; there shouldn't 49 be any. (pgindent leaves *.BAK files behind if it has trouble, while 50 perltidy leaves *.LOG files behind.) 51 522) Do a full test build: 53 54 make -s clean 55 make -s all # look for unexpected warnings, and errors of course 56 make check-world 57 58 Your configure switches should include at least --enable-tap-tests 59 or else much of the Perl code won't get exercised. 60 The ecpg regression tests may well fail due to pgindent's updates of 61 header files that get copied into ecpg output; if so, adjust the 62 expected-files to match. 63 643) If you have the patience, it's worth eyeballing the "git diff" output 65 for any egregiously ugly changes. See below for cleanup ideas. 66 67 68When you're done, "git commit" everything including the typedefs.list file 69you used. 70 71 72--------------------------------------------------------------------------- 73 74Cleaning up in case of failure or ugly output 75--------------------------------------------- 76 77If you don't like the results for any particular file, "git checkout" 78that file to undo the changes, patch the file as needed, then repeat 79the indent process. 80 81pgindent will reflow any comment block that's not at the left margin. 82If this messes up manual formatting that ought to be preserved, protect 83the comment block with some dashes: 84 85 /*---------- 86 * Text here will not be touched by pgindent. 87 *---------- 88 */ 89 90Odd spacing around typedef names might indicate an incomplete typedefs list. 91 92pgindent can get confused by #if sequences that look correct to the compiler 93but have mismatched braces/parentheses when considered as a whole. Usually 94that looks pretty unreadable to humans too, so best practice is to rearrange 95the #if tests to avoid it. 96 97Sometimes, if pgindent or perltidy produces odd-looking output, it's because 98of minor bugs like extra commas. Don't hesitate to clean that up while 99you're at it. 100 101--------------------------------------------------------------------------- 102 103BSD indent 104---------- 105 106We have standardized on FreeBSD's indent, and renamed it pg_bsd_indent. 107pg_bsd_indent does differ slightly from FreeBSD's version, mostly in 108being more easily portable to non-BSD platforms. You can obtain it from 109https://git.postgresql.org/git/pg_bsd_indent.git 110 111GNU indent, version 2.2.6, has several problems, and is not recommended. 112These bugs become pretty major when you are doing >500k lines of code. 113If you don't believe me, take a directory and make a copy. Run pgindent 114on the copy using GNU indent, and do a diff -r. You will see what I 115mean. GNU indent does some things better, but mangles too. For details, 116see: 117 118 http://archives.postgresql.org/pgsql-hackers/2003-10/msg00374.php 119 http://archives.postgresql.org/pgsql-hackers/2011-04/msg01436.php 120 121--------------------------------------------------------------------------- 122 123Which files are processed 124------------------------- 125 126The pgindent run processes (nearly) all PostgreSQL *.c and *.h files, 127but we currently exclude *.y and *.l files, as well as *.c and *.h files 128derived from *.y and *.l files. Additional exceptions are listed 129in exclude_file_patterns: 130 131src/include/storage/s_lock.h and src/include/port/atomics/ are excluded 132because they contain assembly code that pgindent tends to mess up. 133 134src/backend/utils/fmgrtab.c is excluded because it confuses pgindent 135and it's a derived file anyway. 136 137src/interfaces/ecpg/test/expected/ is excluded to avoid breaking the ecpg 138regression tests, since what ecpg generates is not necessarily formatted 139as pgindent would do it. (Note that we do not exclude ecpg's header files 140from the run; some of them get copied verbatim into ecpg's output, meaning 141that the expected files may need to be updated to match.) 142 143src/include/snowball/libstemmer/ and src/backend/snowball/libstemmer/ 144are excluded because those files are imported from an external project, 145not maintained locally, and are machine-generated anyway. Likewise for 146plperl/ppport.h. 147 148 149The perltidy run processes all *.pl and *.pm files, plus a few 150executable Perl scripts that are not named that way. See the "find" 151rules in pgperltidy for details. 152