1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
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. Its source code is in the
sibling directory src/tools/pg_bsd_indent; see the directions
in that directory's README file.
2) Install perltidy. Please be sure it is version 20170521 (older and newer
versions make different formatting choices, and we want consistency).
You can get the correct version from
https://cpan.metacpan.org/authors/id/S/SH/SHANCOCK/
To install, follow the usual install process for a Perl module
("man perlmodinstall" explains it). Or, if you have cpan installed,
this should work:
cpan SHANCOCK/Perl-Tidy-20170521.tar.gz
Or if you have cpanm installed, you can just use:
cpanm https://cpan.metacpan.org/authors/id/S/SH/SHANCOCK/Perl-Tidy-20170521.tar.gz
DOING THE INDENT RUN:
1) Change directory to the top of the source tree.
2) Download the latest typedef file from the buildfarm:
wget -O src/tools/pgindent/typedefs.list https://buildfarm.postgresql.org/cgi-bin/typedefs.pl
(See https://buildfarm.postgresql.org/cgi-bin/typedefs.pl?show_list for a full
list of typedef files, if you want to indent some back branch.)
3) 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.
4) 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.
5) Reformat the bootstrap catalog data files:
./configure # "make" will not work in an unconfigured tree
cd src/include/catalog
make reformat-dat-files
cd ../../..
VALIDATION:
1) Check for any newly-created files using "git status"; there shouldn't
be any. (pgindent leaves *.BAK files behind if it has trouble, while
perltidy leaves *.LOG files behind.)
2) Do a full test build:
make -s clean
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.
The ecpg regression tests may well fail due to pgindent's updates of
header files that get copied into ecpg output; if so, adjust the
expected-files to match.
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.
4) Add the newly created commits to the .git-blame-ignore-revs file so
that "git blame" ignores the commits (for anybody that has opted-in
to using the ignore file). Follow the instructions that appear at
the top of the .git-blame-ignore-revs file.
Another "git commit" will be required for your ignore file changes.
---------------------------------------------------------------------------
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 will mangle both declaration and definition of a C function whose
name matches a typedef. Currently the best workaround is to choose
non-conflicting names.
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 FreeBSD's indent, and renamed it pg_bsd_indent.
pg_bsd_indent does differ slightly from FreeBSD's version, mostly in
being more easily portable to non-BSD platforms. You can obtain it from
https://git.postgresql.org/git/pg_bsd_indent.git
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, as well as *.c and *.h files
derived from *.y and *.l files. Additional exceptions are listed
in exclude_file_patterns; see the notes therein for rationale.
Note that we do not exclude ecpg's header files from the run. Some of them
get copied verbatim into ecpg's output, meaning that ecpg's expected files
may need to be updated to match.
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.
|
