From 47d6d641dda58cf2c25f11a67d6a8ac22c1c97a3 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Fri, 21 Nov 2008 16:46:19 +0000 Subject: Include the platform "FAQs" into the installation instructions. I weeded out some really old information along the way. FAQ_AIX needs separate consideration and will be dealt with later. --- doc/src/sgml/install-win32.sgml | 8 +- doc/src/sgml/installation.sgml | 664 +++++++++++++++++++++++++++++++++++++++- 2 files changed, 660 insertions(+), 12 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/install-win32.sgml b/doc/src/sgml/install-win32.sgml index 3a6bc45301f..632e769e215 100644 --- a/doc/src/sgml/install-win32.sgml +++ b/doc/src/sgml/install-win32.sgml @@ -1,4 +1,4 @@ - + Installation on <productname>Windows</productname> @@ -32,9 +32,9 @@ Building using MinGW or Cygwin uses the normal build system, see - and the FAQs in - doc/FAQ_MINGW and do/FAQ_CYGWIN. - Note that Cygwin is not recommended, and should + and the specific notes in + and . + Cygwin is not recommended and should only be used for older versions of Windows where the native build does not work, such as Windows 98. diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index cee4681ce39..7c86d2521fb 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -1,4 +1,4 @@ - + <![%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 + + + This section documents additional platform-specific issues + regarding the installation and setup of PostgreSQL. Be sure to + read the installation instructions, and in + particular as well. Also, + check src/test/regress/README and the documentation]]> + ]]> regarding the + interpretation of regression test results. + + + + Platforms that are not covered here have no known platform-specific + installation issues. + + + + Cygwin + + + Cyginw + installation on + + + + PostgreSQL can be built using Cygwin, a Linux-like environment for + Windows, but that method is inferior to the native Windows build + )]]> and + is no longer recommended. + + + + When building from source, proceed according to the normal + installation procedure (i.e., ./configure; + make; etc.), noting the following-Cygwin specific + differences: + + + + + Set your path to use the Cygwin bin directory before the + Windows utilities. This will help prevent problems with + compilation. + + + + + + The GNU make command is called "make" not "gmake". + + + + + + The adduser command is not supported; use + the appropriate user management application on Windows NT, + 2000, or XP. Otherwise, skip this step. + + + + + + The su command is not supported; use ssh to + simulate su on Windows NT, 2000, or XP. Otherwise, skip this + step. + + + + + + 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 PostgreSQL server or initialize a database cluster + (initdb). 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. + + + + + + The parallel regression tests (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 make + variable MAX_CONNECTIONS thus: + +make MAX_CONNECTIONS=5 check + + (On some systems you can have up to about 10 simultaneous + connections). + + + + + + + It is possible to install cygserver and the + PostgreSQL server as Windows NT services. For information on how + to do this, please refer to the README + document included with the PostgreSQL binary package on Cygwin. + It is installed in the + directory /usr/share/doc/Cygwin. + + + + + HP-UX + + + HP-UX + installation on + + + + 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. + + + + 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 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 and + 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 + . Don't forget to + get and install binutils at the same time. + + + + 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 + in CFLAGS. + + + + 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 + + + + + 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 + switch to configure. + + + + 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. + + + + + IRIX + + + IRIX + installation on + + + + 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. + + + + 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 + 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. The 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. + + + + 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. If you encounter + this, please let us know so we can develop a proper fix. + + + + 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. + + + + + MinGW/Native Windows + + + MinGW + installation on + + + + PostgreSQL for Windows can be built using MinGW, a Unix-like build + environment for Microsoft operating systems, or using + Microsoft's Visual C++ 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 ]]>. + There is also a precompiled binary installer which you can find at + from . + 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. + + + + 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 configure, can be downloaded + from . Neither is + required to run the resulting binaries; they are needed only for + creating the binaries. + + + + After you have everything installed, it is suggested that you + run psql + under CMD.EXE, as the MSYS console has + buffering issues. + + + + + SCO OpenServer and SCO UnixWare + + + SCO + installation on + + + + UnixWare + installation on + + + + 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. + + + + 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. 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 . + + + + Skunkware has different versions for UnixWare and OpenServer. + Make sure you install the correct version for your operating + system, except as noted below. + + + + On UnixWare 7.1.3 and beyond, the GCC compiler is included on the + UDK CD as is GNU Make. + + + + + 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 + + + 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 . + + + + 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-libraries=/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-libraries=/udk/usr/lib --with-includes=/udk/usr/include + + Putting these together with the Readline options from above: + +./configure --with-libraries="/udk/usr/lib /usr/local/lib" --with-includes="/udk/usr/include /usr/local/include" + + + + + + 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, for example: + +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 + 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. + + + + + <option>--enable-thread-safety</option> and UnixWare + + + If you use the configure + option , + you must use + on all libpqiusing programs. libpq + uses pthread_* calls, which are only + available with the + + + + + + Solaris + + + Solaris + installation on + + + + PostgreSQL is well-supported on Solaris. The more up to date your + operating system, the fewer issues you will experience; details + below. + + + + Note that PostgreSQL is bundled with Solaris 10 (from update 2). + Official packages are also available on + . + Packages for older Solaris versions (8, 9) you can be obtained + from or + . + + + + Required tools + + + 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. + + + + You can download Sun Studio + from . + 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 + or . If you prefer + sources, look + at . + + + + + Problems with OpenSSL + + + 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. + + + + + configure complains about a failed test program + + + If configure 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 LDFLAGS environment + variable on the configure command line, e.g., + +configure ... LDFLAGS="-R /usr/sfw/lib:/opt/sfw/lib:/usr/local/lib" + + See + the ld1 + man page for more information. + + + + + 64-bit build sometimes crashes + + + 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. + + + + + Compiling for optimal performance + + + On the SPARC architecture, Sun Studio is strongly recommended for + compilation. Try using the optimization + flag to generate significantly faster binaries. Do not use any + flags that modify behavior of floating-point operations + and errno processing (e.g., + ). 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. + + + + Some tricks for tuning PostgreSQL and Solaris for performance can + be found + at . + This article is primary focused on T2000 platform, but many of + the recommendations are also useful on other hardware with + Solaris. + + + + + Using DTrace for tracing PostgreSQL + + + Yes, using DTrace is possible. See + ]]> for further + information. You can also find more information in this + article: . + + + + 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. + + + + + -- cgit v1.2.3