Debian Codegraph @

src/tools/pgindent/README

raw
1 pgindent'ing the PostgreSQL source tree
2 =======================================
3
4 pgindent is used to maintain uniform layout style in our C and Perl code,
5 and should be run for every commit. There are additional code beautification
6 tasks which should be performed at least once per release cycle.
7
8 You might find this blog post interesting:
9 http://adpgtech.blogspot.com/2015/05/running-pgindent-on-non-core-code-or.html
10
11
12 PREREQUISITES:
13
14 1) Install pg_bsd_indent in your PATH. Its source code is in the
15 sibling directory src/tools/pg_bsd_indent; see the directions
16 in that directory's README file.
17
18 2) Install perltidy. Please be sure it is version 20230309 (older and newer
19 versions make different formatting choices, and we want consistency).
20 You can get the correct version from
21 https://cpan.metacpan.org/authors/id/S/SH/SHANCOCK/
22 To install, follow the usual install process for a Perl module
23 ("man perlmodinstall" explains it). Or, if you have cpan installed,
24 this should work:
25 cpan SHANCOCK/Perl-Tidy-20230309.tar.gz
26 Or if you have cpanm installed, you can just use:
27 cpanm https://cpan.metacpan.org/authors/id/S/SH/SHANCOCK/Perl-Tidy-20230309.tar.gz
28
29
30 DOING THE INDENT RUN BEFORE A NORMAL COMMIT:
31
32 1) Change directory to the top of the source tree.
33
34 2) Run pgindent on the C files:
35
36 src/tools/pgindent/pgindent .
37
38 If any files generate errors, restore their original versions with
39 "git checkout", and see below for cleanup ideas.
40
41 3) Check for any newly-created files using "git status"; there shouldn't
42 be any. (pgindent leaves *.BAK files behind if it has trouble, while
43 perltidy leaves *.LOG files behind.)
44
45 4) If pgindent wants to change anything your commit wasn't touching,
46 stop and figure out why. If it is making ugly whitespace changes
47 around typedefs your commit adds, you need to add those typedefs
48 to src/tools/pgindent/typedefs.list.
49
50 5) If you have the patience, it's worth eyeballing the "git diff" output
51 for any egregiously ugly changes. See below for cleanup ideas.
52
53 6) Do a full test build:
54
55 make -s clean
56 make -s all # look for unexpected warnings, and errors of course
57 make check-world
58
59 Your configure switches should include at least --enable-tap-tests
60 or else much of the Perl code won't get exercised.
61 The ecpg regression tests may well fail due to pgindent's updates of
62 header files that get copied into ecpg output; if so, adjust the
63 expected-files to match.
64
65
66 AT LEAST ONCE PER RELEASE CYCLE:
67
68 1) Download the latest typedef file from the buildfarm:
69
70 wget -O src/tools/pgindent/typedefs.list https://buildfarm.postgresql.org/cgi-bin/typedefs.pl
71
72 This step resolves any differences between the incrementally updated
73 version of the file and a clean, autogenerated one.
74 (See https://buildfarm.postgresql.org/cgi-bin/typedefs.pl?show_list for
75 a full list of typedef files, if you want to indent some back branch.)
76
77 2) Run pgindent as above.
78
79 3) Indent the Perl code using perltidy:
80
81 src/tools/pgindent/pgperltidy .
82
83 If you want to use some perltidy version that's not in your PATH,
84 first set the PERLTIDY environment variable to point to it.
85
86 4) Reformat the bootstrap catalog data files:
87
88 ./configure # "make" will not work in an unconfigured tree
89 cd src/include/catalog
90 make reformat-dat-files
91 cd ../../..
92
93 5) When you're done, "git commit" everything including the typedefs.list file
94 you used.
95
96 6) Add the newly created commit(s) to the .git-blame-ignore-revs file so
97 that "git blame" ignores the commits (for anybody that has opted-in
98 to using the ignore file). Follow the instructions that appear at
99 the top of the .git-blame-ignore-revs file.
100
101 Another "git commit" will be required for your ignore file changes.
102
103 ---------------------------------------------------------------------------
104
105 Cleaning up in case of failure or ugly output
106 ---------------------------------------------
107
108 If you don't like the results for any particular file, "git checkout"
109 that file to undo the changes, patch the file as needed, then repeat
110 the indent process.
111
112 pgindent will reflow any comment block that's not at the left margin.
113 If this messes up manual formatting that ought to be preserved, protect
114 the comment block with some dashes:
115
116 /*----------
117 * Text here will not be touched by pgindent.
118 */
119
120 Odd spacing around typedef names might indicate an incomplete typedefs list.
121
122 pgindent will mangle both declaration and definition of a C function whose
123 name matches a typedef. Currently the best workaround is to choose
124 non-conflicting names.
125
126 pgindent can get confused by #if sequences that look correct to the compiler
127 but have mismatched braces/parentheses when considered as a whole. Usually
128 that looks pretty unreadable to humans too, so best practice is to rearrange
129 the #if tests to avoid it.
130
131 Sometimes, if pgindent or perltidy produces odd-looking output, it's because
132 of minor bugs like extra commas. Don't hesitate to clean that up while
133 you're at it.
134
135 ---------------------------------------------------------------------------
136
137 BSD indent
138 ----------
139
140 We have standardized on FreeBSD's indent, and renamed it pg_bsd_indent.
141 pg_bsd_indent does differ slightly from FreeBSD's version, mostly in
142 being more easily portable to non-BSD platforms. Find it in the
143 sibling directory src/tools/pg_bsd_indent.
144
145 GNU indent, version 2.2.6, has several problems, and is not recommended.
146 These bugs become pretty major when you are doing >500k lines of code.
147 If you don't believe me, take a directory and make a copy. Run pgindent
148 on the copy using GNU indent, and do a diff -r. You will see what I
149 mean. GNU indent does some things better, but mangles too. For details,
150 see:
151
152 http://archives.postgresql.org/pgsql-hackers/2003-10/msg00374.php
153 http://archives.postgresql.org/pgsql-hackers/2011-04/msg01436.php
154
155 ---------------------------------------------------------------------------
156
157 Which files are processed
158 -------------------------
159
160 The pgindent run processes (nearly) all PostgreSQL *.c and *.h files,
161 but we currently exclude *.y and *.l files, as well as *.c and *.h files
162 derived from *.y and *.l files. Additional exceptions are listed
163 in exclude_file_patterns; see the notes therein for rationale.
164
165 Note that we do not exclude ecpg's header files from the run. Some of them
166 get copied verbatim into ecpg's output, meaning that ecpg's expected files
167 may need to be updated to match.
168
169 The perltidy run processes all *.pl and *.pm files, plus a few
170 executable Perl scripts that are not named that way. See the "find"
171 rules in pgperltidy for details.