mirror/postgresql
2
0
Fork 0
mirror of https://git.postgresql.org/git/postgresql.git synced 2024-12-27 08:39:28 +08:00
Code Issues Packages Projects Releases Wiki Activity

Include the platform "FAQs" into the installation instructions.

Browse Source 
I weeded out some really old information along the way.
FAQ_AIX needs separate consideration and will be dealt with later.
This commit is contained in:
Peter Eisentraut 2008-11-21 16:46:19 +00:00
parent 5758d5ea31
commit 47d6d641dd
8 changed files with 660 additions and 674 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
doc/FAQ_CYGWIN
View File

@ -1,102 +0,0 @@
Installing PostgreSQL on Windows Using Cygwin FAQ
=================================================
$Date: 2007/10/09 01:28:24 $
PostgreSQL requires the appropriate subset of Cygwin DLLs to be
installed in order that it functions under Windows.
This document assumes that you do not have Cygwin already installed
on your system. If that is not the case, then you will need to
adjust these instructions accordingly.
1. Download and run the Cygwin installer. Visit http://cygwin.com/ and
click on the "Install Cygwin now' link. This will prompt you
to download a "setup.exe". Save this file somewhere on your
system and then execute it.
2. Proceed through the Cygwin install wizard. Choose 'Install from
Internet', specify a Local Package Directory and choose a mirror
site that's close to you. Answer the other installer questions
appropriately for your configuration.
When you come to the point of choosing which packages to install,
expand the 'Database' section and click 'Skip' next to PostgreSQL
to change it to the latest version of PostgreSQL available for
Cygwin.
3. Once the download and install process is complete, open a Cygwin
shell and do the following for a basic installation:
3a. Start cygserver for shared memory support. To do this,
enter the command "/usr/sbin/cygserver &". This program
needs to be running anytime you start the Postgres server
or initialize a database (initdb).
3b. Use the initdb command to create a new database cluster. An
example command would be:
initdb -D /usr/local/pgsql/data -W -E LATIN1
Which will create a cluster in the /usr/local/pgsql/data
directory, will prompt for a superuser password and will
set the default database encoding to LATIN1.
3c. Start up the Postgres server. Use a command similar to the
following:
postgres -D /usr/local/pgsql/data
This will start the server, and if successful you will
see some initial log entries, and an entry "LOG: database
system is ready".
4. You are now running a PostgreSQL server on your Windows machine.
5. It is possible to install cygserver and the Postgres server as
Windows NT services. For information on how to do this, please
refer to the README document included with Cygwin PostgreSQL. It
is installed in the /usr/share/doc/Cygwin directory.
Building from source
--------------------
There are some points that are only relevant if you are building Cygwin
PostgreSQL from source:
1. Set your path to use the Cygwin bin directory before the Windows
utilities. This will help prevent problems with compilation.
2. Proceed according to the INSTALL file (i.e., ./configure; make; etc.)
noting the following Cygwin specific differences:
o The GNU make command is called "make" not "gmake".
o The adduser command is not supported -- use the appropriate
user management application on Windows NT, 2000, or XP.
Otherwise, skip this step.
o The su command is not supported -- use ssh to simulate su
on Windows NT, 2000, or XP. Otherwise, skip this step.
Alternatively, proceed according to the README file supplied with
the Cygwin PostgreSQL package.
Known issues
------------
1. Cygwin's AF_UNIX sockets are really implemented as AF_INET sockets
so they are inherently insecure.
2. "make check" can generate spurious regression test failures due to
overflowing the listen() backlog queue which causes connection
refused errors or hangs. You can limit the number of connections
using the MAX_CONNECTIONS option thus:
make MAX_CONNECTIONS=5 check
(On some systems you can have up to about 10 simultaneous connections).
3. The default cygserver configuration may need to be changed (e.g.,
increase SEMMNS) to prevent PostgreSQL from failing due to a lack of
system resources.
Problem reports can be sent to pgsql-cygwin@postgresql.org.

86
doc/FAQ_HPUX
View File

@ -1,86 +0,0 @@
=======================================================
Frequently Asked Questions (FAQ) for PostgreSQL
HP-UX Specific
TO BE READ IN CONJUNCTION WITH THE NORMAL FAQ
=======================================================
last updated: $Date: 2006/12/06 15:45:30 $
current maintainer: Tom Lane (tgl@sss.pgh.pa.us)
original author: Tom Lane (tgl@sss.pgh.pa.us)
Questions covered here:
1.1) What do I need to install PostgreSQL on HP-UX?
1.2) Anything special about the build/install procedure?
1.3) OK, it seemed to build and install, but the regression test fails.
----------------------------------------------------------------------
Section 1: Installing PostgreSQL
----------------------------------------------------------------------
1.1) What do I need to install PostgreSQL on HP-UX?
PostgreSQL 7.3+ should work on Series 700/800 PA-RISC machines running
HP-UX 10.X or 11.X, given appropriate system patch levels and build
tools. At least one developer routinely tests on HPUX 10.20 and we
have reports of successful installations on HPUX 11.00 and 11.11.
Aside from the PostgreSQL source distribution, you will need GNU make
(HP's make will not do), and either GNU gcc or HP's full ANSI C compiler.
If you intend to build from CVS sources rather than a distribution tarball,
you will also need flex (GNU lex) and bison (GNU yacc).
I'd also recommend making sure you are fairly up-to-date on HP
patches. At a minimum, if you are building 64 bit binaries on on HPUX
11.11 you may need PHSS_30966 (11.11) or a successor patch otherwise
initdb may hang:
PHSS_30966 s700_800 ld(1) and linker tools cumulative patch
On general principles you should be current on libc and ld/dld
patches, as well as compiler patches if you are using HP's C compiler.
See HP's support sites such as http://itrc.hp.com and
ftp://us-ffs.external.hp.com/ for free copies of their latest patches.
If you are building on a PA-RISC 2.0 machine and want to have 64-bit
binaries using GCC, you must use GCC 64-bit version. GCC binaries for
HP-UX PA-RISC and Itanium are available from http://www.hp.com/go/gcc.
Don't forget to get and install binutils at the same time.
If you are building on a HP-UX Itanium machine, you will need the
latest HP ANSI C compiler with its dependent patch or successor
patches:
PHSS_30848 s700_800 HP C Compiler (A.05.57)
PHSS_30849 s700_800 u2comp/be/plugin library Patch
1.2) Anything special about the build/install procedure?
If you have both HP's C compiler and GCC's, then you might want to
explicitly select the compiler to use when you run `configure':
./configure CC=cc
for HP's C compiler, or
./configure CC=gcc
for GCC. If you omit this setting, then configure will pick gcc
if it has a choice.
The default install target location is /usr/local/pgsql, which
you might want to change to something under /opt. If so, use
the --prefix switch to configure.
If you are building on a PA-RISC 2.0 machine and want the compiled
binaries to run on PA-RISC 1.1 machines you will need to specify
+DAportable in CFLAGS.
1.3) OK, it seemed to build and install, but the regression test fails.
There are several "expected failures" due to differences between HPUX
and the regression test reference platform used by the PostgreSQL
group. All of these should be compensated for by the regression test
comparison mechanism, with the possible exception of some
low-order-digit differences in the geometry tests, which vary depending
on which compiler and math library versions you use.
Any other error is cause for suspicion.

67
doc/FAQ_IRIX
View File

@ -1,67 +0,0 @@
=======================================================
Frequently Asked Questions (FAQ) for PostgreSQL
IRIX Specific
TO BE READ IN CONJUNCTION WITH THE NORMAL FAQ
=======================================================
last updated: $Date: 2007/10/28 22:33:25 $
current maintainer: Luis Amigo (lamigo@atc.unican.es)
original author: Luis Amigo (lamigo@atc.unican.es)
Questions covered here:
1.1) What do I need to install PostgreSQL on IRIX?
1.2) Anything special about the build/install procedure?
1.3) OK, it seemed to build and install, but the regression test fails.
----------------------------------------------------------------------
Section 1: Installing PostgreSQL
----------------------------------------------------------------------
1.1) What do I need to install PostgreSQL on IRIX?
PostgreSQL has been reported to run successfully on MIPS r8000, r10000(both
ip25 and ip27) and r12000(ip35) processors, running IRIX 6.5.5m, 6.5.12,
6.5.13, and 6.5.26 with MIPSPro compilers version 7.30, 7.3.1.2m, 7.3, and
7.4.4m.
Aside from the PostgreSQL source distribution, you will need GNU make
(SGI's make will not do), and the MIPSPro full ANSI C compiler.
There are problems trying to build with GCC. It is a known gcc bug
(not fixed as of version 3.0) related to using functions that return
certain kinds of structures. This bug affects functions like
inet_ntoa, inet_lnaof, inet_netof, inet_makeaddr and semctl. It is
supposed to be fixed by forcing code to link those functions with
libgcc, but this has not been tested yet.
It is known that version 7.4.1m of the MIPSPro compiler generates
incorrect code. (Symptom is "invalid primary checkpoint record"
when trying to start the database.) Version 7.4.4m is OK; the status
of intermediate versions is uncertain.
1.2) Anything special about the build/install procedure?
There may be a compilation problem like the following:
cc-1020 cc: ERROR File = pqcomm.c, Line = 427
The identifier "TCP_NODELAY" is undefined.
if (setsockopt(port->sock, IPPROTO_TCP, TCP_NODELAY,
Some versions include TCP definitions in <sys/xti.h>, so it is necessary to
add #include <sys/xti.h> in src/backend/libpq/pqcomm.c and in
src/interfaces/libpq/fe-connect.c.
1.3) OK, it seemed to build and install, but the regression test fails.
There are several "expected failures" due to differences between your platform
and the regression test reference platform used by the PostgreSQL group. All
of these should be compensated for by the regression test comparison
mechanism, with the possible exception of some low-order-digit differences in
the geometry tests (depending on which FPU are you using).
Any other error is cause for suspicion.

55
doc/FAQ_MINGW
View File

@ -1,55 +0,0 @@
Compiling PostgreSQL On Native Win32 FAQ
Last updated: Thu Oct 14 18:22:57 EDT 2004
Current maintainer: Bruce Momjian <bruce@momjian.us>
The most recent version of this document can be viewed at
http://www.postgresql.org/docs/faqs.FAQ_MINGW.html.
The FAQ Running & Installing PostgreSQL On Native Windows is at
http://pginstaller.projects.postgresql.org/faq/FAQ_windows.html.
The native Win32 port is built from source using MinGW tools. There
is also a precompiled binary installer called pginstaller which you
can find at from http://pgfoundry.org/projects/pginstaller. It is a
fully native build and uses no additional software like MinGW. The
ready-made installer files are available on the main PostgreSQL ftp
servers in the binary/win32 directory.
Tools for Building Binaries
The native Win32 port requires a 32-bit NT-based Microsoft operating
system, like Windows NT 4, Windows 2000/2003, or Windows XP. (NT 4 is
no longer supported since version 8.2) Earlier operating systems do
not have sufficient infrastructure. Building the port also requires
MinGW and Msys, which can be downloaded from http://www.mingw.org/.
MinGW is a Unix-like build environment for Microsoft operating
systems. Msys is a collection of unix tools required to run shell
scripts like configure. Neither is required to run the resulting
binaries; they are needed only for creating the binaries. Work is in
progress to support building using Visual C++ in a future version.
Steps For Building Binaries
* Download the nightly snapshot tarball from
ftp://ftp.postgresql.org/pub/dev or checkout via CVS (you will
need bison, flex, and perl installed to build from CVS)
* Run configure (you might need to add the --without-zlib argument,
depending on whether you have installed zlib on MinGW)
* Run make install
Note: it is suggested that you run psql under CMD.EXE., as the Msys
console has buffering issues.
If you make a change that you want to contribute, make a context diff
and send it to the mailing list.
Resources
There are several resources that helped us complete this port:
* PeerDirect port of PostgreSQL 7.2 to Win32
* CONNX Win32 signal
* SRA port of PostgreSQL to Win32 (unfortunately, this is not
* pgAdmin3 CHM help files

185
doc/FAQ_SCO
View File

@ -1,185 +0,0 @@
=======================================================
Frequently Asked Questions (FAQ) for PostgreSQL
IRIX Specific
TO BE READ IN CONJUNCTION WITH THE NORMAL FAQ
=======================================================
last updated: $Date: 2006/12/05 14:47:34 $
current maintainer: Billy G. Allie (Bill.Allie@mug.org)
original author: Andrew Merrill (andrew@compclass.com)
Consult http://buildfarm.postgresql.org/ for latest information.
PostgreSQL 8.0 can be built on SCO UnixWare 7 and SCO OpenServer 5.
On OpenServer, you can use either the OpenServer Development Kit or
the Universal Development Kit.
However, some tweaking may be needed, as described below.
Topics:
*) Skunkware
*) GNU Make
*) Readline
*) Using the UDK on OpenServer
*) Compiling PostgreSQL using the UDK
*) Reading the PostgreSQL man pages
*) C99 Issues with the 7.1.1b Feature Supplement
*) --enable-thread-safety and UnixWare
*) float4/float8 regression failures on NaN and inf I/O.
***************************************************************************
*) Skunkware
You should locate your copy of the SCO Skunkware CD. The Skunkware CD is
included with UnixWare 7 and current versions of OpenServer 5.
Skunkware includes ready-to-install versions of many popular programs that
are available on the Internet. For example, gzip, gunzip, GNU make, flex,
and bison are all included.
If you do not have this CD, the software on it is available via anonymous
ftp from ftp.sco.com/skunkware.
For UnixWare 7.1, this CD is now labeled "Open License Software Supplement".
Skunkware has different versions for UnixWare and OpenServer. Make sure
you install the correct version for your operating system, except as noted
below.
Note: on UnixWare 7.1.3 and beyond, the GCC compiler is included on the UDK
CD as is GNUMake.
***************************************************************************
*) GNU Make
You need to use the GNU make program, which is on the Skunkware CD. By
default, it installs as /usr/local/bin/make. To avoid confusion with the
SCO make program, you may want to rename GNU make to gmake.
As of UnixWare 7.1.3 and above, the GNU Make program is is the OSTK portion
of the UDK CD, and is in /usr/gnu/bin/gmake.
***************************************************************************
*) Readline
If you install the readline library, then psql (the PostgreSQL command line
SQL interpreter) remembers each command you type, and allows you to use
arrow keys to recall and edit previous commands. This is very helpful, and
is strongly recommended. The readline library is on the Skunkware CD.
The readline library is not included on the UnixWare 7.1 Skunkware CD. If
you have the UnixWare 7.0.0 or 7.0.1 Skunkware CDs, you can install it from
there. Otherwise, try ftp.sco.com/skunkware.
By default, readline installs into /usr/local/lib and /usr/local/include.
However, the PostgreSQL configure program will not find it there without
help. If you installed readline, then use the following options to
configure:
configure --with-libs=/usr/local/lib --with-includes=/usr/local/include
***************************************************************************
*) Using the UDK on OpenServer
If you are using the new Universal Development Kit (UDK) compiler on
OpenServer, you need to specify the locations of the UDK libraries:
configure --with-libs=/udk/usr/lib --with-includes=/udk/usr/include
Putting these together with the readline options from above:
./configure --with-libs="/udk/usr/lib /usr/local/lib" --with-includes="/udk/usr/include /usr/local/include"
***************************************************************************
*) Compiling PostgreSQL 7.1 with the UDK
The program, backend/utils/adt/int8.c, tickles a compiler bug with in the
following versions (and probably others as well) of the C compiler:
Optimizing C Compilation System (CCS) 3.2 08/18/98
Optimizing C Compilation System (CCS) 3.2 09/28/99
If you encounter an error compiling backend/utils/adt/int8.c, please apply
the following patch:
------------------------------8< CUT HERE >8------------------------------
*** src/backend/utils/adt/int8.c.orig Sat Oct 7 20:48:17 2000
--- src/backend/utils/adt/int8.c Sat Oct 7 20:52:03 2000
***************
*** 489,495 ****
if (arg1 < 1)
result = 0;
else
! for (i = arg1, result = 1; i > 0; --i)
result *= i;
PG_RETURN_INT64(result);
--- 489,495 ----
if (arg1 < 1)
result = 0;
else
! for (i = arg1, result = 1; i; --i)
result *= i;
PG_RETURN_INT64(result);
------------------------------8< CUT HERE >8------------------------------
This compiler bug seems to be fixed at least in
Optimizing C Compilation System (CCS) 4.0 10/23/00 (UDK FS 7.1.1b)
***************************************************************************
*) Reading the PostgreSQL man pages
By default, the PostgreSQL man pages are installed into
/usr/local/pgsql/man. By default, UnixWare does not look there for
man pages. To be able to read them you need to modify the MANPATH
variable in /etc/default/man. I use:
MANPATH=/usr/lib/scohelp/%L/man:/usr/dt/man:/usr/man:/usr/share/man:scohelp:/usr/local/man:/usr/local/pgsql/man
On OpenServer, some extra research needs to be invested to make the
man pages usable, because the man system is a bit different from other
platforms. Currently, PostgreSQL will not install them at all.
***************************************************************************
*) C99 Issues with the 7.1.1b Feature Supplement
For compilers earlier than the one released with OpenUNIX 8.0.0(UnixWare
7.1.2), Including the 7.1.1b Feature Supplement, you may need to specify -Xb
in CFLAGS or the CC environment variable. The indication of this is an
error in compiling tuplesort.c referencing inline functions.
Apparently there was a change in the 7.1.2(8.0.0) compiler and beyond.
***************************************************************************
*) --enable-thread-safety and UnixWare
If you use the --enable-thread-safety configure flag, you *MUST* use -Kpthread
on ALL libpq using programs.
libpq uses pthread_* calls, which are only available with the
-Kpthread/-Kthread flag.
***************************************************************************
*) float4/float8 regression failures on NaN and inf I/O.
You will see regression failures for the float4 and float8 regression
tests on the NaN and inf I/O functions. This is due to a bug in SCO's strtod
library function on BOTH UnixWare and OpenServer. It's slated to be fixed
in the first maintenance / update for UnixWare 7.1.4, and probably the
next MP/UP for OpenServer 5.0.7 (I'm not sure on the OSR side as of the time
I'm writing this (2004-05-14).
You might also see Join test failures due to ordering differences, and these
are ok.

167
doc/FAQ_Solaris
View File

@ -1,167 +0,0 @@
============================================================
Frequently Asked Questions (FAQ) for PostgreSQL
Sun Solaris specific
To be read in conjunction with the installation instructions.
============================================================
Last updated: $Date: 2007/02/27 19:10:19 $
Contents:
1) What tools do I need to build and install PostgreSQL on Solaris?
2) Why do I get problems when building with OpenSSL support?
3) Why does configure complain about a failed test program?
4) Why does my 64-bit build sometimes crash?
5) How can I compile for optimum performance?
6) Where I can download prepared Solaris packages?
7) How can I tune PostgreSQL and Solaris for performance?
8) Can I use DTrace for tracing PostgreSQL?
1) What tools do I need to build and install PostgreSQL on Solaris?
You will need
gzip (for installing the documentation)
GNU Make
GNU Readline library (optional)
Sun Studio CC or GCC
You can download Sun Studio from:
http://developers.sun.com/prodtech/cc/downloads/index.jsp
Many of GNU tools are integrated into Solaris 10, or they are present
on the Solaris companion CD.
If you like packages for older version of Solaris, you can find these
tools here:
http://www.sunfreeware.com or http://www.blastwave.org
If you prefer sources, look here:
http://www.gnu.org/order/ftp.html
You can build with either GCC or Sun's compiler suite. For better
code optimization, Sun's compiler is strongly recommended on the SPARC
architecture. We have heard reports of problems when using GCC
2.95.1; gcc 2.95.3 or later is recommended. If you are using Sun's
compiler, be careful not to select /usr/ucb/cc; use
/opt/SUNWspro/bin/cc.
2) Why do I get problems when building with OpenSSL support?
When you build PostgreSQL with OpenSSL support you might get compilation
errors in the following files:
src/backend/libpq/crypt.c
src/backend/libpq/password.c
src/interfaces/libpq/fe-auth.c
src/interfaces/libpq/fe-connect.c
This is because of a namespace conflict between the standard
/usr/include/crypt.h header and the header files provided by OpenSSL.
Upgrading your OpenSSL installation to version 0.9.6a fixes this
problem. Solaris 9 and above has a newer version of OpenSSL.
3) Why does configure complain about a failed test program?
This is probably a case of the run-time linker being unable to find
some library, probably libz, libreadline or some other non-standard
library such as libssl. To point it to the right location, set the
LDFLAGS environment variable, e.g.,
LDFLAGS="-R /usr/sfw/lib:/opt/sfw/lib:/usr/local/lib"
export LDFLAGS
and restart configure. See the ld(1) man page for more
information.
4) Why does my 64-bit build sometimes crash?
On Solaris 7 and older, the 64-bit version of libc has a buggy vsnprintf
routine, which leads to erratic core dumps in PostgreSQL. The simplest
known workaround is to force PostgreSQL to use its own version of
vsnprintf rather than the library copy. To do this, after you run
'configure' edit a file produced by configure:
In src/Makefile.global, change the line
LIBOBJS =
to read
LIBOBJS = snprintf.o
(There might be other files already listed in this variable. Order
does not matter.)
Then build as usual.
5) How can I compile for optimal performance?
On the SPARC architecture, Sun Studio is strongly recommended for
compilation. Try using the -xO5 optimization flag to generate
significantly faster binaries. Do not use any flags that modify
behavior of floating point operations and errno processing (e.g.,
-fast). These flags could raise some nonstandard PostgreSQL behavior
for example in the date/time computing.
If you do not have a reason to use 64-bit binaries on SPARC, prefer
the 32-bit version. The 64-bit operations are slower and 64-bit
binaries are slower than the 32-bit variants. And on other hand,
32-bit code on the AMD64 CPU family is not native, and that is why
32-bit code is significant slower on this CPU family.
6) Where I can download prepared Solaris packages?
The PostgreSQL is bundled with Solaris 10 (from update 2). Official
packages are also available on
<http://pgfoundry.org/projects/solarispackages/>. Packages for older
Solaris version (8, 9) you can be obtained from
<http://www.sunfreeware.com/> or <http://www.blastwave.org/>.
7) How can I tune PostgreSQL and Solaris for performance?
Some tuning tricks can be found here:
http://www.sun.com/servers/coolthreads/tnb/applications_postgresql.jsp
This article is primary focused on T2000 platform, but many of the
recommendations are also useful on other hardware with Solaris.
8) Can I use DTrace for tracing PostgreSQL?
Yes, see the chapter "Monitoring Database Activity" in the documentation
for further information.
You can also find more information here:
http://blogs.sun.com/robertlor/entry/user_level_dtrace_probes_in
If you see the linking of the postgres executable abort with an error
message like
Undefined first referenced
symbol in file
AbortTransaction utils/probes.o
CommitTransaction utils/probes.o
ld: fatal: Symbol referencing errors. No output written to postgres
collect2: ld returned 1 exit status
gmake: *** [postgres] Error 1
your DTrace installation is too old to handle probes in static
functions. You need Solaris 10u4 or newer. Workaround is remove static
keyword from AbortTransaction and CommitTransaction functions declaration in
src/backend/access/transam/xact.c.
See http://sunsolve.sun.com/search/document.do?assetkey=1-1-2139224-1
(registration required).

8
doc/src/sgml/install-win32.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/install-win32.sgml,v 1.49 2008/07/29 15:23:44 mha Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/install-win32.sgml,v 1.50 2008/11/21 16:46:19 petere Exp $ -->
<chapter id="install-win32">
<title>Installation on <productname>Windows</productname></title>
@ -32,9 +32,9 @@
<para>
Building using <productname>MinGW</productname> or
<productname>Cygwin</productname> uses the normal build system, see
<xref linkend="installation"> and the FAQs in
<filename>doc/FAQ_MINGW</filename> and <filename>do/FAQ_CYGWIN</filename>.
Note that <productname>Cygwin</productname> is not recommended, and should
<xref linkend="installation"> and the specific notes in
<xref linkend="installation-notes-mingw"> and <xref linkend="installation-notes-cygwin">.
<productname>Cygwin</productname> is not recommended and should
only be used for older versions of <productname>Windows</productname> where
the native build does not work, such as
<productname>Windows 98</productname>.

664
doc/src/sgml/installation.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.313 2008/09/05 12:11:18 petere Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.314 2008/11/21 16:46:19 petere Exp $ -->
<chapter id="installation">
<title><![%standalone-include[<productname>PostgreSQL</>]]>
@ -96,7 +96,9 @@ su - postgres
<para>
<application>tar</> is required to unpack the source
distribution in the first place, in addition to either
<application>gzip</> or <application>bzip2</>.
<application>gzip</> or <application>bzip2</>. In
addition, <application>gzip</> is required to install the
documentation.
</para>
</listitem>
@ -109,9 +111,12 @@ su - postgres
<primary>libedit</primary>
</indexterm>
The <acronym>GNU</> <productname>Readline</> library (for
simple line editing and command history retrieval) is
used by default. If you don't want to use it then you must specify
The <acronym>GNU</> <productname>Readline</> library is used by
default. It allows <application>psql</application> (the
PostgreSQL command line SQL interpreter) to remember each
command you type, and allows you to use arrow keys to recall and
edit previous commands. This is very helpful and is strongly
recommended. If you don't want to use it then you must specify
the <option>--without-readline</option> option for
<filename>configure</>. As an alternative, you can often use the
BSD-licensed <filename>libedit</filename> library, originally
@ -2001,8 +2006,9 @@ kill `cat /usr/local/pgsql/data/postmaster.pid`
FreeBSD, OpenBSD, NetBSD, Mac OS X, AIX, HP/UX, IRIX, Solaris, Tru64 Unix,
and UnixWare. Other Unix-like systems may also work but are not currently
being tested. In most cases, all CPU architectures supported by
a given operating system will work. Look in the <filename>doc/</>
directory of the source distribution to see if there is a FAQ document
a given operating system will work. Look in
the <xref linkend="installation-platform-notes"> below to see if
there is information
specific to your operating system, particularly if using an older system.
</para>
@ -2011,9 +2017,651 @@ kill `cat /usr/local/pgsql/data/postmaster.pid`
to be supported according to recent build farm results, please report
it to <email>pgsql-bugs@postgresql.org</email>. If you are interested
in porting <productname>PostgreSQL</> to a new platform,
<email>pgsql-ports@postgresql.org</email> is the appropriate place
<email>pgsql-hackers@postgresql.org</email> is the appropriate place
to discuss that.
</para>
</sect1>
<sect1 id="installation-platform-notes">
<title>Platform-Specific Notes</title>
<para>
This section documents additional platform-specific issues
regarding the installation and setup of PostgreSQL. Be sure to
read the installation instructions, and in
particular <xref linkend="install-requirements"> as well. Also,
check <![%standalone-include[the
file <filename>src/test/regress/README</> and the documentation]]>
<![%standalone-ignore[<xref linkend="regress">]]> regarding the
interpretation of regression test results.
</para>
<para>
Platforms that are not covered here have no known platform-specific
installation issues.
</para>
<sect2 id="installation-notes-cygwin">
<title>Cygwin</title>
<indexterm zone="installation-notes-cygwin">
<primary>Cyginw</primary>
<secondary>installation on</secondary>
</indexterm>
<para>
PostgreSQL can be built using Cygwin, a Linux-like environment for
Windows, but that method is inferior to the native Windows build
<![%standalone-ignore[(see <xref linkend="install-win32">)]]> and
is no longer recommended.
</para>
<para>
When building from source, proceed according to the normal
installation procedure (i.e., <literal>./configure;
make</literal>; etc.), noting the following-Cygwin specific
differences:
<itemizedlist>
<listitem>
<para>
Set your path to use the Cygwin bin directory before the
Windows utilities. This will help prevent problems with
compilation.
</para>
</listitem>
<listitem>
<para>
The GNU make command is called "make" not "gmake".
</para>
</listitem>
<listitem>
<para>
The <command>adduser</command> command is not supported; use
the appropriate user management application on Windows NT,
2000, or XP. Otherwise, skip this step.
</para>
</listitem>
<listitem>
<para>
The <command>su</command> command is not supported; use ssh to
simulate su on Windows NT, 2000, or XP. Otherwise, skip this
step.
</para>
</listitem>
<listitem>
<para>
Start <command>cygserver</command> for shared memory support.
To do this, enter the command <literal>/usr/sbin/cygserver
&</literal>. This program needs to be running anytime you
start the PostgreSQL server or initialize a database cluster
(<command>initdb</command>). The
default <command>cygserver</command> configuration may need to
be changed (e.g., increase <symbol>SEMMNS</symbol>) to prevent
PostgreSQL from failing due to a lack of system resources.
</para>
</listitem>
<listitem>
<para>
The parallel regression tests (<literal>make check</literal>)
can generate spurious regression test failures due to
overflowing the <function>listen()</function> backlog queue
which causes connection refused errors or hangs. You can limit
the number of connections using the make
variable <varname>MAX_CONNECTIONS</varname> thus:
<programlisting>
make MAX_CONNECTIONS=5 check
</programlisting>
(On some systems you can have up to about 10 simultaneous
connections).
</para>
</listitem>
</itemizedlist>
</para>
<para>
It is possible to install <command>cygserver</command> and the
PostgreSQL server as Windows NT services. For information on how
to do this, please refer to the <filename>README</filename>
document included with the PostgreSQL binary package on Cygwin.
It is installed in the
directory <filename>/usr/share/doc/Cygwin</filename>.
</para>
</sect2>
<sect2 id="installation-notes-hpux">
<title>HP-UX</title>
<indexterm zone="installation-notes-hpux">
<primary>HP-UX</primary>
<secondary>installation on</secondary>
</indexterm>
<para>
PostgreSQL 7.3+ should work on Series 700/800 PA-RISC machines
running HP-UX 10.X or 11.X, given appropriate system patch levels
and build tools. At least one developer routinely tests on HP-UX
10.20, and we have reports of successful installations on HP-UX
11.00 and 11.11.
</para>
<para>
Aside from the PostgreSQL source distribution, you will need GNU
make (HP's make will not do), and either GCC or HP's full ANSI C
compiler. If you intend to build from CVS sources rather than a
distribution tarball, you will also need Flex (GNU lex) and Bison
(GNU yacc). We also recommend making sure you are fairly
up-to-date on HP patches. At a minimum, if you are building 64
bit binaries on on HP-UX 11.11 you may need PHSS_30966 (11.11) or a
successor patch otherwise <command>initdb</command> may hang:
<literallayout>
PHSS_30966 s700_800 ld(1) and linker tools cumulative patch
</literallayout>
On general principles you should be current on libc and ld/dld
patches, as well as compiler patches if you are using HP's C
compiler. See HP's support sites such
as <ulink url="http://itrc.hp.com"></ulink> and
<ulink url="ftp://us-ffs.external.hp.com/"></ulink> for free
copies of their latest patches.
</para>
<para>
If you are building on a PA-RISC 2.0 machine and want to have
64-bit binaries using GCC, you must use GCC 64-bit version. GCC
binaries for HP-UX PA-RISC and Itanium are available from
<ulink url="http://www.hp.com/go/gcc"></ulink>. Don't forget to
get and install binutils at the same time.
</para>
<para>
If you are building on a PA-RISC 2.0 machine and want the compiled
binaries to run on PA-RISC 1.1 machines you will need to specify
<option>+DAportable</option> in <envar>CFLAGS</envar>.
</para>
<para>
If you are building on a HP-UX Itanium machine, you will need the
latest HP ANSI C compiler with its dependent patch or successor
patches:
<literallayout>
PHSS_30848 s700_800 HP C Compiler (A.05.57)
PHSS_30849 s700_800 u2comp/be/plugin library Patch
</literallayout>
</para>
<para>
If you have both HP's C compiler and GCC's, then you might want to
explicitly select the compiler to use when you
run <command>configure</command>:
<programlisting>
./configure CC=cc
</programlisting>
for HP's C compiler, or
<programlisting>
./configure CC=gcc
</programlisting>
for GCC. If you omit this setting, then configure will
pick <command>gcc</command> if it has a choice.
</para>
<para>
The default install target location
is <filename>/usr/local/pgsql</filename>, which you might want to
change to something under <filename>/opt</filename>. If so, use
the
<option>--prefix</option> switch to <command>configure</command>.
</para>
<para>
In the regression tests, there might be some low-order-digit
differences in the geometry tests, which vary depending on which
compiler and math library versions you use. Any other error is
cause for suspicion.
</para>
</sect2>
<sect2 id="installation-notes-irix">
<title>IRIX</title>
<indexterm zone="installation-notes-irix">
<primary>IRIX</primary>
<secondary>installation on</secondary>
</indexterm>
<para>
PostgreSQL has been reported to run successfully on MIPS r8000,
r10000 (both ip25 and ip27) and r12000(ip35) processors, running
IRIX 6.5.5m, 6.5.12, 6.5.13, and 6.5.26 with MIPSPro compilers
version 7.30, 7.3.1.2m, 7.3, and 7.4.4m.
</para>
<para>
You will need the MIPSPro full ANSI C compiler. There are
problems trying to build with GCC. It is a known GCC bug (not
fixed as of version 3.0) related to using functions that return
certain kinds of structures. This bug affects functions like
<function>inet_ntoa</>, <function>inet_lnaof</>, <function>inet_netof</>, <function>inet_makeaddr</>,
and <function>semctl</>. It is supposed to be fixed by forcing
code to link those functions with libgcc, but this has not been
tested yet.
</para>
<para>
It is known that version 7.4.1m of the MIPSPro compiler generates
incorrect code. The symptom is <quote>invalid primary checkpoint
record</quote> when trying to start the database.) Version 7.4.4m
is OK; the status of intermediate versions is uncertain.
</para>
<para>
There may be a compilation problem like the following:
<screen>
cc-1020 cc: ERROR File = pqcomm.c, Line = 427
The identifier "TCP_NODELAY" is undefined.
if (setsockopt(port->sock, IPPROTO_TCP, TCP_NODELAY,
</screen>
Some versions include TCP definitions
in <filename>sys/xti.h</filename>, so it is necessary to
add <literal>#include &lt;sys/xti.h&gt;</literal>
in <filename>src/backend/libpq/pqcomm.c</> and in
<filename>src/interfaces/libpq/fe-connect.c</>. If you encounter
this, please let us know so we can develop a proper fix.
</para>
<para>
In the regression tests, there might be some low-order-digit
differences in the geometry tests, depending on which FPU are you
using. Any other error is cause for suspicion.
</para>
</sect2>
<sect2 id="installation-notes-mingw">
<title>MinGW/Native Windows</title>
<indexterm zone="installation-notes-mingw">
<primary>MinGW</primary>
<secondary>installation on</secondary>
</indexterm>
<para>
PostgreSQL for Windows can be built using MinGW, a Unix-like build
environment for Microsoft operating systems, or using
Microsoft's <productname>Visual C++</productname> compiler suite.
The MinGW build variant uses the normal build system described in
this chapter; the Visual C++ build works completely differently
and is described in <![%standalone-include[the
documentation]]><![%standalone-ignore[<xref linkend="install-win32">]]>.
There is also a precompiled binary installer which you can find at
from <ulink url="http://pgfoundry.org/projects/pginstaller"></ulink>.
It is a fully native build and uses no additional software like
MinGW. The ready-made installer files are available on the main
PostgreSQL FTP servers in the <filename>binary/win32</filename>
directory.
</para>
<para>
The native Win32 port requires a 32-bit NT-based Microsoft
operating system, like Windows NT 4, Windows 2000/2003, or Windows
XP. (NT 4 is no longer supported.) Earlier operating systems do
not have sufficient infrastructure (but Cygwin may be used on
those). MinGW, the Unix-like build tools, and MSYS, a collection
of Unix tools required to run shell scripts
like <command>configure</command>, can be downloaded
from <ulink url="http://www.mingw.org/"></ulink>. Neither is
required to run the resulting binaries; they are needed only for
creating the binaries.
</para>
<para>
After you have everything installed, it is suggested that you
run <application>psql</application>
under <command>CMD.EXE</command>, as the MSYS console has
buffering issues.
</para>
</sect2>
<sect2 id="installation-notes-sco">
<title>SCO OpenServer and SCO UnixWare</title>
<indexterm zone="installation-notes-sco">
<primary>SCO</primary>
<secondary>installation on</secondary>
</indexterm>
<indexterm zone="installation-notes-sco">
<primary>UnixWare</primary>
<secondary>installation on</secondary>
</indexterm>
<para>
PostgreSQL can be built on SCO UnixWare 7 and SCO OpenServer 5.
On OpenServer, you can use either the OpenServer Development Kit
or the Universal Development Kit. However, some tweaking may be
needed, as described below.
</para>
<sect3>
<title>Skunkware</title>
<para>
You should locate your copy of the SCO Skunkware CD. The
Skunkware CD is included with UnixWare 7 and current versions of
OpenServer 5. Skunkware includes ready-to-install versions of
many popular programs that are available on the Internet. For
example, gzip, gunzip, GNU Make, Flex, and Bison are all
included. For UnixWare 7.1, this CD is now labeled "Open License
Software Supplement". If you do not have this CD, the software
on it is available via anonymous FTP
from <ulink url="ftp://ftp.sco.com/skunkware"></ulink>.
</para>
<para>
Skunkware has different versions for UnixWare and OpenServer.
Make sure you install the correct version for your operating
system, except as noted below.
</para>
<para>
On UnixWare 7.1.3 and beyond, the GCC compiler is included on the
UDK CD as is GNU Make.
</para>
</sect3>
<sect3>
<title>GNU Make</title>
<para>
You need to use the GNU Make program, which is on the Skunkware
CD. By default, it installs
as <filename>/usr/local/bin/make</filename>. To avoid confusion
with the SCO <filename>make</filename> program, you may want to rename GNU <filename>make</filename> to
<filename>gmake</filename>.
</para>
<para>
As of UnixWare 7.1.3 and above, the GNU Make program is is the
OSTK portion of the UDK CD, and is
in <filename>/usr/gnu/bin/gmake</filename>.
</para>
</sect3>
<sect3>
<title>Readline</title>
<para>
The Readline library is on the Skunkware CD. But it is not
included on the UnixWare 7.1 Skunkware CD. If you have the
UnixWare 7.0.0 or 7.0.1 Skunkware CDs, you can install it from
there. Otherwise,
try <ulink url="ftp://ftp.sco.com/skunkware"></ulink>.
</para>
<para>
By default, Readline installs into <filename>/usr/local/lib</> and
<filename>/usr/local/include</>. However, the
PostgreSQL <command>configure</command> program will not find it
there without help. If you installed Readline, then use the
following options to <command>configure</command>:
<programlisting>
./configure --with-libraries=/usr/local/lib --with-includes=/usr/local/include
</programlisting>
</para>
</sect3>
<sect3>
<title>Using the UDK on OpenServer</title>
<para>
If you are using the new Universal Development Kit (UDK) compiler
on OpenServer, you need to specify the locations of the UDK
libraries:
<programlisting>
./configure --with-libraries=/udk/usr/lib --with-includes=/udk/usr/include
</programlisting>
Putting these together with the Readline options from above:
<programlisting>
./configure --with-libraries="/udk/usr/lib /usr/local/lib" --with-includes="/udk/usr/include /usr/local/include"
</programlisting>
</para>
</sect3>
<sect3>
<title>Reading the PostgreSQL man pages</title>
<para>
By default, the PostgreSQL man pages are installed into
<filename>/usr/local/pgsql/man</filename>. By default, UnixWare
does not look there for man pages. To be able to read them you
need to modify the
<varname>MANPATH</varname> variable
in <filename>/etc/default/man</filename>, for example:
<programlisting>
MANPATH=/usr/lib/scohelp/%L/man:/usr/dt/man:/usr/man:/usr/share/man:scohelp:/usr/local/man:/usr/local/pgsql/man
</programlisting>
</para>
<para>
On OpenServer, some extra research needs to be invested to make
the man pages usable, because the man system is a bit different
from other platforms. Currently, PostgreSQL will not install
them at all.
</para>
</sect3>
<sect3>
<title>C99 Issues with the 7.1.1b Feature Supplement</title>
<para>
For compilers earlier than the one released with OpenUNIX 8.0.0
(UnixWare 7.1.2), including the 7.1.1b Feature Supplement, you
may need to specify <option>-Xb</option>
in <varname>CFLAGS</varname> or the <varname>CC</varname>
environment variable. The indication of this is an error in
compiling <filename>tuplesort.c</filename> referencing inline
functions. Apparently there was a change in the 7.1.2(8.0.0)
compiler and beyond.
</para>
</sect3>
<sect3>
<title><option>--enable-thread-safety</option> and UnixWare</title>
<para>
If you use the <command>configure</command>
option <option>--enable-thread-safety</option>,
you <emphasis>must</emphasis> use <option>-Kpthread</option>
on <emphasis>all</emphasis> libpqiusing programs. libpq
uses <function>pthread_*</function> calls, which are only
available with the
<option>-Kpthread</>/<option>-Kthread</> flag.
</para>
</sect3>
</sect2>
<sect2 id="installation-notes-solaris">
<title>Solaris</title>
<indexterm zone="installation-notes-solaris">
<primary>Solaris</primary>
<secondary>installation on</secondary>
</indexterm>
<para>
PostgreSQL is well-supported on Solaris. The more up to date your
operating system, the fewer issues you will experience; details
below.
</para>
<para>
Note that PostgreSQL is bundled with Solaris 10 (from update 2).
Official packages are also available on
<ulink url="http://pgfoundry.org/projects/solarispackages/"></ulink>.
Packages for older Solaris versions (8, 9) you can be obtained
from <ulink url="http://www.sunfreeware.com/"></ulink> or
<ulink url="http://www.blastwave.org/"></ulink>.
</para>
<sect3>
<title>Required tools</title>
<para>
You can build with either GCC or Sun's compiler suite. For
better code optimization, Sun's compiler is strongly recommended
on the SPARC architecture. We have heard reports of problems
when using GCC 2.95.1; gcc 2.95.3 or later is recommended. If
you are using Sun's compiler, be careful not to select
<filename>/usr/ucb/cc</filename>;
use <filename>/opt/SUNWspro/bin/cc</filename>.
</para>
<para>
You can download Sun Studio
from <ulink url="http://developers.sun.com/sunstudio/downloads/"></ulink>.
Many of GNU tools are integrated into Solaris 10, or they are
present on the Solaris companion CD. If you like packages for
older version of Solaris, you can find these tools
at <ulink url="http://www.sunfreeware.com"></ulink>
or <ulink url="http://www.blastwave.org"></ulink>. If you prefer
sources, look
at <ulink url="http://www.gnu.org/order/ftp.html"></ulink>.
</para>
</sect3>
<sect3>
<title>Problems with OpenSSL</title>
<para>
When you build PostgreSQL with OpenSSL support you might get
compilation errors in the following files:
<itemizedlist>
<listitem><para><filename>src/backend/libpq/crypt.c</filename></para></listitem>
<listitem><para><filename>src/backend/libpq/password.c</filename></para></listitem>
<listitem><para><filename>src/interfaces/libpq/fe-auth.c</filename></para></listitem>
<listitem><para><filename>src/interfaces/libpq/fe-connect.c</filename></para></listitem>
</itemizedlist>
This is because of a namespace conflict between the standard
<filename>/usr/include/crypt.h</filename> header and the header
files provided by OpenSSL.
</para>
<para>
Upgrading your OpenSSL installation to version 0.9.6a fixes this
problem. Solaris 9 and above has a newer version of OpenSSL.
</para>
</sect3>
<sect3>
<title>configure complains about a failed test program</title>
<para>
If <command>configure</command> complains about a failed test
program, this is probably a case of the run-time linker being
unable to find some library, probably libz, libreadline or some
other non-standard library such as libssl. To point it to the
right location, set the <envar>LDFLAGS</envar> environment
variable on the <command>configure</command> command line, e.g.,
<programlisting>
configure ... LDFLAGS="-R /usr/sfw/lib:/opt/sfw/lib:/usr/local/lib"
</programlisting>
See
the <citerefentry><refentrytitle>ld</><manvolnum>1</></citerefentry>
man page for more information.
</para>
</sect3>
<sect3>
<title>64-bit build sometimes crashes</title>
<para>
On Solaris 7 and older, the 64-bit version of libc has a buggy
<function>vsnprintf</function> routine, which leads to erratic
core dumps in PostgreSQL. The simplest known workaround is to
force PostgreSQL to use its own version of vsnprintf rather than
the library copy. To do this, after you
run <command>configure</command> edit a file produced by
<command>configure</command>:
In <filename>src/Makefile.global</filename>, change the line
<programlisting>
LIBOBJS =
</programlisting>
to read
<programlisting>
LIBOBJS = snprintf.o
</programlisting>
(There might be other files already listed in this variable.
Order does not matter.) Then build as usual.
</para>
</sect3>
<sect3>
<title>Compiling for optimal performance</title>
<para>
On the SPARC architecture, Sun Studio is strongly recommended for
compilation. Try using the <option>-xO5</option> optimization
flag to generate significantly faster binaries. Do not use any
flags that modify behavior of floating-point operations
and <varname>errno</varname> processing (e.g.,
<option>-fast</option>). These flags could raise some
nonstandard PostgreSQL behavior for example in the date/time
computing.
</para>
<para>
If you do not have a reason to use 64-bit binaries on SPARC,
prefer the 32-bit version. The 64-bit operations are slower and
64-bit binaries are slower than the 32-bit variants. And on
other hand, 32-bit code on the AMD64 CPU family is not native,
and that is why 32-bit code is significant slower on this CPU
family.
</para>
<para>
Some tricks for tuning PostgreSQL and Solaris for performance can
be found
at <ulink url="http://www.sun.com/servers/coolthreads/tnb/applications_postgresql.jsp"></ulink>.
This article is primary focused on T2000 platform, but many of
the recommendations are also useful on other hardware with
Solaris.
</para>
</sect3>
<sect3>
<title>Using DTrace for tracing PostgreSQL</title>
<para>
Yes, using DTrace is possible. See <![%standalone-include[the
documentation]]>
<![%standalone-ignore[<xref linkend="monitoring">]]> for further
information. You can also find more information in this
article: <ulink url="http://blogs.sun.com/robertlor/entry/user_level_dtrace_probes_in"></ulink>.
</para>
<para>
If you see the linking of the postgres executable abort with an
error message like
<screen>
Undefined first referenced
symbol in file
AbortTransaction utils/probes.o
CommitTransaction utils/probes.o
ld: fatal: Symbol referencing errors. No output written to postgres
collect2: ld returned 1 exit status
gmake: *** [postgres] Error 1
</screen>
your DTrace installation is too old to handle probes in static
functions. You need Solaris 10u4 or newer.
</para>
</sect3>
</sect2>
</sect1>
</chapter>