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