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://buildfarm.postgresql.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
834) Add the newly created commits to the .git-blame-ignore-revs file so
84 that "git blame" ignores the commits (for anybody that has opted-in
85 to using the ignore file).
86
87Another "git commit" will be required for your ignore file changes.
88
89---------------------------------------------------------------------------
90
91Cleaning up in case of failure or ugly output
92---------------------------------------------
93
94If you don't like the results for any particular file, "git checkout"
95that file to undo the changes, patch the file as needed, then repeat
96the indent process.
97
98pgindent will reflow any comment block that's not at the left margin.
99If this messes up manual formatting that ought to be preserved, protect
100the comment block with some dashes:
101
102 /*----------
103 * Text here will not be touched by pgindent.
104 *----------
105 */
106
107Odd spacing around typedef names might indicate an incomplete typedefs list.
108
109pgindent will mangle both declaration and definition of a C function whose
110name matches a typedef. Currently the best workaround is to choose
111non-conflicting names.
112
113pgindent can get confused by #if sequences that look correct to the compiler
114but have mismatched braces/parentheses when considered as a whole. Usually
115that looks pretty unreadable to humans too, so best practice is to rearrange
116the #if tests to avoid it.
117
118Sometimes, if pgindent or perltidy produces odd-looking output, it's because
119of minor bugs like extra commas. Don't hesitate to clean that up while
120you're at it.
121
122---------------------------------------------------------------------------
123
124BSD indent
125----------
126
127We have standardized on FreeBSD's indent, and renamed it pg_bsd_indent.
128pg_bsd_indent does differ slightly from FreeBSD's version, mostly in
129being more easily portable to non-BSD platforms. You can obtain it from
130https://git.postgresql.org/git/pg_bsd_indent.git
131
132GNU indent, version 2.2.6, has several problems, and is not recommended.
133These bugs become pretty major when you are doing >500k lines of code.
134If you don't believe me, take a directory and make a copy. Run pgindent
135on the copy using GNU indent, and do a diff -r. You will see what I
136mean. GNU indent does some things better, but mangles too. For details,
137see:
138
139 http://archives.postgresql.org/pgsql-hackers/2003-10/msg00374.php
140 http://archives.postgresql.org/pgsql-hackers/2011-04/msg01436.php
141
142---------------------------------------------------------------------------
143
144Which files are processed
145-------------------------
146
147The pgindent run processes (nearly) all PostgreSQL *.c and *.h files,
148but we currently exclude *.y and *.l files, as well as *.c and *.h files
149derived from *.y and *.l files. Additional exceptions are listed
150in exclude_file_patterns; see the notes therein for rationale.
151
152Note that we do not exclude ecpg's header files from the run. Some of them
153get copied verbatim into ecpg's output, meaning that ecpg's expected files
154may need to be updated to match.
155
156The perltidy run processes all *.pl and *.pm files, plus a few
157executable Perl scripts that are not named that way. See the "find"
158rules in pgperltidy for details.
159