src/tools/pgindent/README

   1 src/tools/pgindent/README
   2
   3 pgindent
   4 ========
   5
   6 This can format all PostgreSQL *.c and *.h files, but excludes *.y, and
   7 *.l files.
   8
   9 1) Change directory to the top of the build tree.
  10
  11 2) Download the typedef file from the buildfarm:
  12
  13         wget -O src/tools/pgindent/typedefs.list http://buildfarm.postgresql.org/cgi-bin/typedefs.pl
  14
  15 3) Remove all derived files (pgindent has trouble with one of the flex macros):
  16
  17         gmake maintainer-clean
  18
  19 4) Run pgindent:
  20
  21         find . -name '*.[ch]' -type f -print | \
  22         egrep -v -f src/tools/pgindent/exclude_file_patterns | \
  23         xargs -n100 pgindent src/tools/pgindent/typedefs.list
  24
  25 5) Remove any files that generate errors and restore their original
  26    versions.
  27
  28 6) Do a full test build:
  29
  30         run configure
  31         # stop is only necessary if it's going to install in a location with an
  32         # already running server
  33         pg_ctl stop
  34         gmake -C src install
  35         gmake -C contrib install
  36         gmake installcheck-world
  37
  38
  39 ---------------------------------------------------------------------------
  40
  41 We have standardized on NetBSD's indent.  We have fixed a few bugs which
  42 requre the NetBSD source to be patched with indent.bsd.patch patch.  A
  43 fully patched version is available at ftp://ftp.postgresql.org/pub/dev.
  44
  45 GNU indent, version 2.2.6, has several problems, and is not recommended.
  46 These bugs become pretty major when you are doing >500k lines of code.
  47 If you don't believe me, take a directory and make a copy.  Run pgindent
  48 on the copy using GNU indent, and do a diff -r. You will see what I
  49 mean. GNU indent does some things better, but mangles too.
  50
  51 Notes about excluded files:
  52
  53 src/include/storage/s_lock.h is excluded because it contains assembly code
  54 that pgindent tends to mess up.
  55
  56 src/include/snowball/libstemmer/ and src/backend/snowball/libstemmer/
  57 are excluded because those files are imported from an external project,
  58 not maintained locally, and are machine-generated anyway.
  59
  60 src/interfaces/ecpg/test/expected/ is excluded to avoid breaking the ecpg
  61 regression tests.  Several *.h files are included in regression output so
  62 should not be changed.
  63
  64 ---------------------------------------------------------------------------
  65
  66 Obsolete typedef list creation instructions:
  67 --------------------------------------------
  68
  69 To use pgindent:
  70
  71 1) Build the source tree with _debug_ symbols and all possible configure options
  72
  73 2) Install to /usr/local/pgsql
  74
  75 3) Install all contrib modules
  76
  77 4) Save a list of typedefs by running:
  78
  79         src/tools/find_typedef /usr/local/pgsql/bin /usr/local/pgsql/lib > /tmp/pgtypedefs