I wrote:
> I was just noticing, while answering a user question, the amount of
> unorganized urban sprawl we've accumulated in
> https://www.postgresql.org/docs/devel/install-procedure.html
> We've got practically-essential options like --prefix and
> --with-openssl intermixed with obscure portability flags
> and options that only developers should take any interest in.
> For bonus points, the ordering seems chosen largely by dartboard;
> there's certainly no visible plan to it.
> I think we should try to improve the situation by dividing the
> configure options into categories and/or separating commonly
> used options from obscure ones. I don't have any concrete
> proposal to make right now, but I am hoping to kick off a
> discussion about what such an organization would look like.
Hearing nothing but crickets, I took a stab at this myself,
ending up with a division into these categories:
Installation Locations
PostgreSQL Features
PostgreSQL Anti-Features
Build Process Details
Miscellaneous
Developer Options
plus a separate section for environment variables.
This seems to me to work fairly well, though surely it's not
the only way things could have been divided. Except for the
"Features" section which contains many commonly-used options,
there's generally only one or two commonly-used options per
section, which I put first. I also added a short para of
advice about which options to use, where it seemed helpful.
DocBook wasn't happy with putting inside a
's step list, so I had to move all this stuff
out of the installation procedure's step list. I'm not
sure whether I like that or not --- it does result in the
step list being fairly short and comprehensible, but the
info that you need to consult for the "configure" step is
now some distance away. It's moot unless somebody knows
another way to do the markup, though.
Because of relocating and re-ordering the options, the diff
is just about unreadable :-(. However, I mostly refrained
from changing the descriptions of individual options.
They're just ordered differently, and there is more text
around them. I did yield to temptation in some small ways
though.
Comments?
regards, tom lane
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 4493862..cdc743c 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -325,12 +325,12 @@ su - postgres
Also check that you have sufficient disk space. You will need about
- 100 MB for the source tree during compilation and about 20 MB for
+ 350 MB for the source tree during compilation and about 60 MB for
the installation directory. An empty database cluster takes about
- 35 MB; databases take about five times the amount of space that a
+ 40 MB; databases take about five times the amount of space that a
flat text file with the same data would take. If you are going to
run the regression tests you will temporarily need up to an extra
- 150 MB. Use the df command to check free disk
+ 300 MB. Use the df command to check free disk
space.
@@ -349,8 +349,11 @@ su - postgres
gunzip postgresql-&version;.tar.gz
tar xf postgresql-&version;.tar
- (Use bunzip2 instead of gunzip if you
- have the .bz2 file.)
+ (Use bunzip2 instead of gunzip if
+ you have the .bz2 file. Also, note that most
+ modern versions of tar can unpack compressed archives
+ directly, so you don't really need the
+ separate gunzip or bunzip2 step.)
This will create a directory
postgresql-&version; under the current directory
with the PostgreSQL sources.
@@ -387,10 +390,14 @@ su - postgres
This script will run a number of tests to determine values for various
system dependent variables and detect any quirks of your
operating system, and finally will create several files in the
-build tree to record what it found. You can also run
-configure in a directory outside the source
-tree, if you want to keep the build directory separate. This
-procedure is also called a
+build tree to record what it found.
+
+
+
+You can also run configure in a directory outside
+the source tree, and then build there, if you want to keep the build
+directory separate from the original source files. This procedure is
+called a
VPATHVPATH
build. Here's how:
@@ -410,8 +417,230 @@ su - postgres
You can customize the build and installation process by supplying one
-or more of the following command line options to
-configure:
+or more command line options to configure.
+Typically you would customize the install location, or the set of
+optional features that are built. configure
+has a large number of options, which are described in
+.
+
+
+
+Also, configure responds to certain environment
+variables, as described in .
+These provide additional ways to customize the configuration.
+
+
+
+
