granicus.if.org Git - postgresql/blob - src/tools/pgindent/README

   1 pgindent
   2 ========
   3
   4 This can format all PostgreSQL *.c and *.h files, but excludes *.y, and
   5 *.l files.
   6
   7 1) Install pg_bsd_indent (see below for details).
   8
   9 2) Install entab (src/tools/entab/).
  10
  11 3) Change directory to the top of the build tree.
  12
  13 4) Remove all derived files (pgindent has trouble with one of the flex macros):
  14
  15         make maintainer-clean
  16
  17    Or:
  18
  19         git clean -fdx
  20
  21 5) Download the typedef file from the buildfarm:
  22
  23         wget -O src/tools/pgindent/typedefs.list http://buildfarm.postgresql.org/cgi-bin/typedefs.pl
  24
  25 6) Run pgindent:
  26
  27         src/tools/pgindent/pgindent
  28
  29 7) Remove any files that generate errors and restore their original
  30    versions.
  31
  32 8) Indent the Perl code:
  33
  34         (
  35                 find . -name \*.pl -o -name \*.pm
  36
  37                 find . -type f -exec file {} \; |
  38                 egrep -i ':.*perl[0-9]*\>' |
  39                 cut -d: -f1
  40         ) |
  41         sort -u |
  42         xargs perltidy --profile=src/tools/pgindent/perltidyrc
  43
  44 9) Do a full test build:
  45
  46         > run configure
  47         # stop is only necessary if it's going to install in a location with an
  48         # already running server
  49         pg_ctl stop
  50         run configure
  51         make -C src install
  52         make -C contrib install
  53         run initdb
  54         pg_ctl start
  55         make installcheck-world
  56
  57 10) Remove Perl backup files after testing
  58
  59 ---------------------------------------------------------------------------
  60
  61 BSD indent
  62 ----------
  63
  64 We have standardized on NetBSD's indent, and renamed it pg_bsd_indent.
  65 We have fixed a few bugs which requre the NetBSD source to be patched
  66 with indent.bsd.patch patch.  A fully patched version is available at
  67 ftp://ftp.postgresql.org/pub/dev.
  68
  69 GNU indent, version 2.2.6, has several problems, and is not recommended.
  70 These bugs become pretty major when you are doing >500k lines of code.
  71 If you don't believe me, take a directory and make a copy.  Run pgindent
  72 on the copy using GNU indent, and do a diff -r. You will see what I
  73 mean. GNU indent does some things better, but mangles too.  For details,
  74 see:
  75
  76         http://archives.postgresql.org/pgsql-hackers/2003-10/msg00374.php
  77         http://archives.postgresql.org/pgsql-hackers/2011-04/msg01436.php
  78
  79 ---------------------------------------------------------------------------
  80
  81 Notes about excluded files
  82 --------------------------
  83
  84 src/include/storage/s_lock.h is excluded because it contains assembly code
  85 that pgindent tends to mess up.
  86
  87 src/include/snowball/libstemmer/ and src/backend/snowball/libstemmer/
  88 are excluded because those files are imported from an external project,
  89 not maintained locally, and are machine-generated anyway.
  90
  91 src/interfaces/ecpg/test/expected/ is excluded to avoid breaking the ecpg
  92 regression tests.  Several *.h files are included in regression output so
  93 should not be changed.
  94
  95 ---------------------------------------------------------------------------
  96
  97 Obsolete typedef list creation instructions
  98 -------------------------------------------
  99
 100 To use pgindent:
 101
 102 1) Build the source tree with _debug_ symbols and all possible configure options
 103
 104 2) Install to /usr/local/pgsql
 105
 106 3) Install all contrib modules
 107
 108 4) Save a list of typedefs by running:
 109
 110         src/tools/find_typedef /usr/local/pgsql/bin /usr/local/pgsql/lib > /tmp/pgtypedefs