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. + + + + + Build + + + To start the build, type either of: + +make +make all + + (Remember to use GNU make.) + The build will take a few minutes depending on your + hardware. The last line displayed should be: + +All of PostgreSQL successfully made. Ready to install. + + + + + If you want to build everything that can be built, including the + documentation (HTML and man pages), and the additional modules + (contrib), type instead: + +make world + + The last line displayed should be: + +PostgreSQL, contrib, and documentation successfully made. Ready to install. + + + + + If you want to invoke the build from another makefile rather than + manually, you must unset MAKELEVEL or set it to zero, + for instance like this: + +build-postgresql: + $(MAKE) -C postgresql MAKELEVEL=0 all + + Failure to do that can lead to strange error messages, typically about + missing header files. + + + + + Regression Tests + + + regression test + + + + If you want to test the newly built server before you install it, + you can run the regression tests at this point. The regression + tests are a test suite to verify that PostgreSQL + runs on your machine in the way the developers expected it + to. Type: + +make check + + (This won't work as root; do it as an unprivileged user.) + See for + detailed information about interpreting the test results. You can + repeat this test at any later time by issuing the same command. + + + + + Installing the Files + + + + If you are upgrading an existing system be sure to read + , + which has instructions about upgrading a + cluster. + + + + + To install PostgreSQL enter: + +make install + + This will install files into the directories that were specified + in . Make sure that you have appropriate + permissions to write into that area. Normally you need to do this + step as root. Alternatively, you can create the target + directories in advance and arrange for appropriate permissions to + be granted. + + + + To install the documentation (HTML and man pages), enter: + +make install-docs + + + + + If you built the world above, type instead: + +make install-world + + This also installs the documentation. + + + + You can use make install-strip instead of + make install to strip the executable files and + libraries as they are installed. This will save some space. If + you built with debugging support, stripping will effectively + remove the debugging support, so it should only be done if + debugging is no longer needed. install-strip + tries to do a reasonable job saving space, but it does not have + perfect knowledge of how to strip every unneeded byte from an + executable file, so if you want to save all the disk space you + possibly can, you will have to do manual work. + + + + The standard installation provides all the header files needed for client + application development as well as for server-side program + development, such as custom functions or data types written in C. + (Prior to PostgreSQL 8.0, a separate make + install-all-headers command was needed for the latter, but this + step has been folded into the standard install.) + + + + Client-only installation: + + If you want to install only the client applications and + interface libraries, then you can use these commands: + +make -C src/bin install +make -C src/include install +make -C src/interfaces install +make -C doc install + + src/bin has a few binaries for server-only use, + but they are small. + + + + + + + Uninstallation: + + To undo the installation use the command make + uninstall. However, this will not remove any created directories. + + + + + Cleaning: + + + After the installation you can free disk space by removing the built + files from the source tree with the command make + clean. This will preserve the files made by the configure + program, so that you can rebuild everything with make + later on. To reset the source tree to the state in which it was + distributed, use make distclean. If you are going to + build for several platforms within the same source tree you must do + this and re-configure for each platform. (Alternatively, use + a separate build tree for each platform, so that the source tree + remains unmodified.) + + + + + If you perform a build and then discover that your configure + options were wrong, or if you change anything that configure + investigates (for example, software upgrades), then it's a good + idea to do make distclean before reconfiguring and + rebuilding. Without this, your changes in configuration choices + might not propagate everywhere they need to. + + + + <filename>configure</filename> Options + + + configure options + + + + configure's command line options are explained below. + This list is not exhaustive (use ./configure --help + to get one that is). The options not covered here are meant for + advanced use-cases such as cross-compilation, and are documented in + the standard Autoconf documentation. + + + + Installation Locations + + + The option is sufficient for most cases. + If you have special needs, you can customize the individual + subdirectories with the other options described in this section. + Beware however that changing the relative locations of the different + subdirectories may render the installation non-relocatable, meaning + you won't be able to move it after installation. + (The man and doc + locations are not affected by this restriction.) + For relocatable installs, you might want to use + the --disable-rpath option described later. + @@ -424,22 +653,6 @@ su - postgres will ever be installed directly into the PREFIX directory. - - - If you have special needs, you can also customize the - individual subdirectories with the following options. However, - if you leave these with their defaults, the installation will be - relocatable, meaning you can move the directory after - installation. (The man and doc - locations are not affected by this.) - - - - For relocatable installs, you might want to use - configure's --disable-rpath - option. Also, you will need to tell the operating system how - to find the shared libraries. - @@ -599,56 +812,21 @@ su - postgres for dynamically loadable modules. - - - - - - - - Append STRING to the PostgreSQL version number. You - can use this, for example, to mark binaries built from unreleased Git - snapshots or containing custom patches with an extra version string - such as a git describe identifier or a - distribution package release number. - - - + - - - - - DIRECTORIES is a colon-separated list of - directories that will be added to the list the compiler - searches for header files. If you have optional packages - (such as GNU Readline) installed in a non-standard - location, - you have to use this option and probably also the corresponding - option. - - - Example: --with-includes=/opt/gnu/include:/usr/sup/include. - - - + + <productname>PostgreSQL</productname> Features - - - - - DIRECTORIES is a colon-separated list of - directories to search for libraries. You will probably have - to use this option (and the corresponding - option) if you have packages - installed in non-standard locations. - - - Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib. - - - + + The options described in this section enable building of + various PostgreSQL features that are not + built by default. Most of them are non-default because they require + additional software, as described in + . + + + @@ -668,22 +846,7 @@ su - postgres To use this option, you will need an implementation of the - Gettext API; see above. - - - - - - - - - Set NUMBER as the default port number for - server and clients. The default is 5432. The port can always - be changed later on, but if you specify it here then both - server and clients will have the same default compiled in, - which can be very convenient. Usually the only good reason - to select a non-default value is if you intend to run multiple - PostgreSQL servers on the same machine. + Gettext API. @@ -730,32 +893,32 @@ su - postgres - + - Build with support for GSSAPI authentication. On many - systems, the GSSAPI (usually a part of the Kerberos installation) - system is not installed in a location - that is searched by default (e.g., /usr/include, - /usr/lib), so you must use the options - and in - addition to this option. configure will check - for the required header files and libraries to make sure that - your GSSAPI installation is sufficient before proceeding. + Build with support for + the ICUICU + library. This requires the ICU4C package + to be installed. The minimum required version + of ICU4C is currently 4.2. - - - - - - The default name of the Kerberos service principal used - by GSSAPI. - postgres is the default. There's usually no - reason to change this unless you have a Windows environment, - in which case it must be set to upper case - POSTGRES. + By default, + pkg-configpkg-config + will be used to find the required compilation options. This is + supported for ICU4C version 4.6 and later. + For older versions, or if pkg-config is + not available, the variables ICU_CFLAGS + and ICU_LIBS can be specified + to configure, like in this example: + +./configure ... --with-icu ICU_CFLAGS='-I/some/where/include' ICU_LIBS='-L/some/where/lib -licui18n -licuuc -licudata' + + (If ICU4C is in the default search path + for the compiler, then you still need to specify a nonempty string in + order to avoid use of pkg-config, for + example, ICU_CFLAGS=' '.) @@ -796,37 +959,6 @@ su - postgres - - - - Build with support for - the ICUICU - library. This requires the ICU4C package - to be installed. The minimum required version - of ICU4C is currently 4.2. - - - - By default, - pkg-configpkg-config - will be used to find the required compilation options. This is - supported for ICU4C version 4.6 and later. - For older versions, or if pkg-config is - not available, the variables ICU_CFLAGS - and ICU_LIBS can be specified - to configure, like in this example: - -./configure ... --with-icu ICU_CFLAGS='-I/some/where/include' ICU_LIBS='-L/some/where/lib -licui18n -licuuc -licudata' - - (If ICU4C is in the default search path - for the compiler, then you still need to specify a nonempty string in - order to avoid use of pkg-config, for - example, ICU_CFLAGS=' '.) - - - - - OpenSSL @@ -846,22 +978,18 @@ su - postgres - - - - Build with PAMPAM - (Pluggable Authentication Modules) support. - - - - - - + - Build with BSD Authentication support. - (The BSD Authentication framework is - currently only available on OpenBSD.) + Build with support for GSSAPI authentication. On many systems, the + GSSAPI system (usually a part of the Kerberos installation) is not + installed in a location + that is searched by default (e.g., /usr/include, + /usr/lib), so you must use the options + and in + addition to this option. configure will check + for the required header files and libraries to make sure that + your GSSAPI installation is sufficient before proceeding. @@ -885,41 +1013,38 @@ su - postgres - + - Build with support - for systemdsystemd - service notifications. This improves integration if the server binary - is started under systemd but has no impact - otherwise; see for more - information. libsystemd and the - associated header files need to be installed to be able to use this - option. + Build with PAMPAM + (Pluggable Authentication Modules) support. - + - Prevents use of the Readline library - (and libedit as well). This option disables - command-line editing and history in - psql, so it is not recommended. + Build with BSD Authentication support. + (The BSD Authentication framework is + currently only available on OpenBSD.) - + - Favors the use of the BSD-licensed libedit library - rather than GPL-licensed Readline. This option - is significant only if you have both libraries installed; the - default in that case is to use Readline. + Build with support + for systemdsystemd + service notifications. This improves integration if the server binary + is started under systemd but has no impact + otherwise; see for more + information. libsystemd and the + associated header files need to be installed to be able to use this + option. @@ -1012,6 +1137,64 @@ su - postgres + + + + + + <productname>PostgreSQL</productname> Anti-Features + + + The options described in this section allow disabling + certain PostgreSQL features that are built + by default, but which might need to be turned off if the required + software or system features are not available. Using these options is + not recommended unless really necessary. + + + + + + + + + Prevents use of the Readline library + (and libedit as well). This option disables + command-line editing and history in + psql. + + + + + + + + + Favors the use of the + BSD-licensed libedit library rather + than GPL-licensed Readline. This + option is significant only if you have both libraries installed; + the default in that case is to + use Readline. + + + + + + + + + + zlib + + Prevents use of the Zlib library. + This disables + support for compressed archives in pg_dump + and pg_restore. + + + + @@ -1047,80 +1230,85 @@ su - postgres - + - Set the segment size, in gigabytes. Large tables are - divided into multiple operating-system files, each of size equal - to the segment size. This avoids problems with file size limits - that exist on many platforms. The default segment size, 1 gigabyte, - is safe on all supported platforms. If your operating system has - largefile support (which most do, nowadays), you can use - a larger segment size. This can be helpful to reduce the number of - file descriptors consumed when working with very large tables. - But be careful not to select a value larger than is supported - by your platform and the file systems you intend to use. Other - tools you might wish to use, such as tar, could - also set limits on the usable file size. - It is recommended, though not absolutely required, that this value - be a power of 2. - Note that changing this value requires an initdb. + Allow the build to succeed even if PostgreSQL + has no CPU spinlock support for the platform. The lack of + spinlock support will result in poor performance; therefore, + this option should only be used if the build aborts and + informs you that the platform lacks spinlock support. If this + option is required to build PostgreSQL on + your platform, please report the problem to the + PostgreSQL developers. - + - Set the block size, in kilobytes. This is the unit - of storage and I/O within tables. The default, 8 kilobytes, - is suitable for most situations; but other values may be useful - in special cases. - The value must be a power of 2 between 1 and 32 (kilobytes). - Note that changing this value requires an initdb. + Disable use of CPU atomic operations. This option does nothing on + platforms that lack such operations. On platforms that do have + them, this will result in poor performance. This option is only + useful for debugging or making performance comparisons. - + - Set the WAL block size, in kilobytes. This is the unit - of storage and I/O within the WAL log. The default, 8 kilobytes, - is suitable for most situations; but other values may be useful - in special cases. - The value must be a power of 2 between 1 and 64 (kilobytes). - Note that changing this value requires an initdb. + Disable the thread-safety of client libraries. This prevents + concurrent threads in libpq and + ECPG programs from safely controlling + their private connection handles. Use this only on platforms + with deficient thread support. + + + + + + Build Process Details + + + - + - Allow the build to succeed even if PostgreSQL - has no CPU spinlock support for the platform. The lack of - spinlock support will result in poor performance; therefore, - this option should only be used if the build aborts and - informs you that the platform lacks spinlock support. If this - option is required to build PostgreSQL on - your platform, please report the problem to the - PostgreSQL developers. + DIRECTORIES is a colon-separated list of + directories that will be added to the list the compiler + searches for header files. If you have optional packages + (such as GNU Readline) installed in a non-standard + location, + you have to use this option and probably also the corresponding + option. + + + Example: --with-includes=/opt/gnu/include:/usr/sup/include. - + - Disable the thread-safety of client libraries. This prevents - concurrent threads in libpq and - ECPG programs from safely controlling - their private connection handles. + DIRECTORIES is a colon-separated list of + directories to search for libraries. You will probably have + to use this option (and the corresponding + option) if you have packages + installed in non-standard locations. + + + Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib. @@ -1166,62 +1354,171 @@ su - postgres - + - - zlib - - Prevents use of the Zlib library. This disables - support for compressed archives in pg_dump - and pg_restore. - This option is only intended for those rare systems where this - library is not available. + Append STRING to the PostgreSQL version number. You + can use this, for example, to mark binaries built from unreleased Git + snapshots or containing custom patches with an extra version string + such as a git describe identifier or a + distribution package release number. - + - Compiles all programs and libraries with debugging symbols. - This means that you can run the programs in a debugger - to analyze problems. This enlarges the size of the installed - executables considerably, and on non-GCC compilers it usually - also disables compiler optimization, causing slowdowns. However, - having the symbols available is extremely helpful for dealing - with any problems that might arise. Currently, this option is - recommended for production installations only if you use GCC. - But you should always have it on if you are doing development work - or running a beta version. + Do not mark PostgreSQL's executables + to indicate that they should search for shared libraries in the + installation's library directory (see ). + On most platforms, this marking uses an absolute path to the + library directory, so that it will be unhelpful if you relocate + the installation later. However, you will then need to provide + some other way for the executables to find the shared libraries. + Typically this requires configuring the operating system's + dynamic linker to search the library directory. + + + + + + Miscellaneous + + + It's fairly common, particularly for test builds, to adjust the + default port number with . + The other options in this section are recommended only for advanced + users. + + + + - + - If using GCC, all programs and libraries are compiled with - code coverage testing instrumentation. When run, they - generate files in the build directory with code coverage - metrics. - See - for more information. This option is for use only with GCC - and when doing development work. + Set NUMBER as the default port number for + server and clients. The default is 5432. The port can always + be changed later on, but if you specify it here then both + server and clients will have the same default compiled in, + which can be very convenient. Usually the only good reason + to select a non-default value is if you intend to run multiple + PostgreSQL servers on the same machine. - + - If using GCC, all programs and libraries are compiled so they - can be profiled. On backend exit, a subdirectory will be created - that contains the gmon.out file for use in profiling. - This option is for use only with GCC and when doing development work. + The default name of the Kerberos service principal used + by GSSAPI. + postgres is the default. There's usually no + reason to change this unless you have a Windows environment, + in which case it must be set to upper case + POSTGRES. + + + + + + + + + Set the segment size, in gigabytes. Large tables are + divided into multiple operating-system files, each of size equal + to the segment size. This avoids problems with file size limits + that exist on many platforms. The default segment size, 1 gigabyte, + is safe on all supported platforms. If your operating system has + largefile support (which most do, nowadays), you can use + a larger segment size. This can be helpful to reduce the number of + file descriptors consumed when working with very large tables. + But be careful not to select a value larger than is supported + by your platform and the file systems you intend to use. Other + tools you might wish to use, such as tar, could + also set limits on the usable file size. + It is recommended, though not absolutely required, that this value + be a power of 2. + Note that changing this value requires an initdb. + + + + + + + + + Set the block size, in kilobytes. This is the unit + of storage and I/O within tables. The default, 8 kilobytes, + is suitable for most situations; but other values may be useful + in special cases. + The value must be a power of 2 between 1 and 32 (kilobytes). + Note that changing this value requires an initdb. + + + + + + + + + Set the WAL block size, in kilobytes. This is the unit + of storage and I/O within the WAL log. The default, 8 kilobytes, + is suitable for most situations; but other values may be useful + in special cases. + The value must be a power of 2 between 1 and 64 (kilobytes). + Note that changing this value requires an initdb. + + + + + + + + + + Developer Options + + + Most of the options in this section are only of interest for + developing or debugging PostgreSQL. + They are not recommended for production builds, except + for , which can be useful to enable + more detailed bug reports in the unlucky event that you encounter a + bug. On platforms supporting DTrace, + may also be reasonable to use in production. + + + + When building an installation that will be used to develop code inside + the server, it is recommended to use at least the + options + and . + + + + + + + + + Compiles all programs and libraries with debugging symbols. + This means that you can run the programs in a debugger + to analyze problems. This enlarges the size of the installed + executables considerably, and on non-GCC compilers it usually + also disables compiler optimization, causing slowdowns. However, + having the symbols available is extremely helpful for dealing + with any problems that might arise. Currently, this option is + recommended for production installations only if you use GCC. + But you should always have it on if you are doing development work + or running a beta version. @@ -1246,6 +1543,17 @@ su - postgres + + + + Enable tests using the Perl TAP tools. This requires a Perl + installation and the Perl module IPC::Run. + See for more information. + + + + + @@ -1260,6 +1568,34 @@ su - postgres + + + + If using GCC, all programs and libraries are compiled with + code coverage testing instrumentation. When run, they + generate files in the build directory with code coverage + metrics. + See + for more information. This option is for use only with GCC + and when doing development work. + + + + + + + + + If using GCC, all programs and libraries are compiled so they + can be profiled. On backend exit, a subdirectory will be created + that contains the gmon.out file containing + profile data. + This option is for use only with GCC and when doing development work. + + + + + @@ -1297,24 +1633,46 @@ su - postgres - - - - - - Enable tests using the Perl TAP tools. This requires a Perl - installation and the Perl module IPC::Run. - See for more information. - - - + + + + + + + <filename>configure</filename> Environment Variables + + + configure environment variables + + + + In addition to the ordinary command-line options described above, + configure responds to a number of environment + variables. + You can specify environment variables on the + configure command line, for example: + +./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe' + + In this usage an environment variable is little different from a + command-line option. + You can also set such variables beforehand: + +export CC=/opt/bin/gcc +export CFLAGS='-O2 -pipe' +./configure + + This usage can be convenient because many programs' configuration + scripts respond to these variables in similar ways. + The most commonly used of these environment variables are + CC and CFLAGS. If you prefer a C compiler different from the one configure picks, you can set the - environment variable CC to the program of your choice. + variable CC to the program of your choice. By default, configure will pick gcc if available, else the platform's default (usually cc). Similarly, you can override the @@ -1322,14 +1680,6 @@ su - postgres - You can specify environment variables on the - configure command line, for example: - -./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe' - - - - Here is a list of the significant variables that can be set in this manner: @@ -1552,13 +1902,6 @@ su - postgres - When developing code inside the server, it is recommended to - use the configure options (which - turns on many run-time error checks) and - (which improves the usefulness of debugging tools). - - - If using GCC, it is best to build with an optimization level of at least , because using no optimization () disables some important compiler warnings (such @@ -1579,187 +1922,8 @@ su - postgres adjustments, while COPT might be kept set all the time. - - - - Build - - - To start the build, type either of: - -make -make all - - (Remember to use GNU make.) - The build will take a few minutes depending on your - hardware. The last line displayed should be: - -All of PostgreSQL successfully made. Ready to install. - - - - - If you want to build everything that can be built, including the - documentation (HTML and man pages), and the additional modules - (contrib), type instead: - -make world - - The last line displayed should be: - -PostgreSQL, contrib, and documentation successfully made. Ready to install. - - - - - If you want to invoke the build from another makefile rather than - manually, you must unset MAKELEVEL or set it to zero, - for instance like this: - -build-postgresql: - $(MAKE) -C postgresql MAKELEVEL=0 all - - Failure to do that can lead to strange error messages, typically about - missing header files. - - - - - Regression Tests - - - regression test - - - - If you want to test the newly built server before you install it, - you can run the regression tests at this point. The regression - tests are a test suite to verify that PostgreSQL - runs on your machine in the way the developers expected it - to. Type: - -make check - - (This won't work as root; do it as an unprivileged user.) - See for - detailed information about interpreting the test results. You can - repeat this test at any later time by issuing the same command. - - - - - Installing the Files - - - - If you are upgrading an existing system be sure to read - , - which has instructions about upgrading a - cluster. - - - - - To install PostgreSQL enter: - -make install - - This will install files into the directories that were specified - in . Make sure that you have appropriate - permissions to write into that area. Normally you need to do this - step as root. Alternatively, you can create the target - directories in advance and arrange for appropriate permissions to - be granted. - - - - To install the documentation (HTML and man pages), enter: - -make install-docs - - - - - If you built the world above, type instead: - -make install-world - - This also installs the documentation. - - - - You can use make install-strip instead of - make install to strip the executable files and - libraries as they are installed. This will save some space. If - you built with debugging support, stripping will effectively - remove the debugging support, so it should only be done if - debugging is no longer needed. install-strip - tries to do a reasonable job saving space, but it does not have - perfect knowledge of how to strip every unneeded byte from an - executable file, so if you want to save all the disk space you - possibly can, you will have to do manual work. - - - - The standard installation provides all the header files needed for client - application development as well as for server-side program - development, such as custom functions or data types written in C. - (Prior to PostgreSQL 8.0, a separate make - install-all-headers command was needed for the latter, but this - step has been folded into the standard install.) - - - - Client-only installation: - - If you want to install only the client applications and - interface libraries, then you can use these commands: - -make -C src/bin install -make -C src/include install -make -C src/interfaces install -make -C doc install - - src/bin has a few binaries for server-only use, - but they are small. - - - - - - - Uninstallation: - - To undo the installation use the command make - uninstall. However, this will not remove any created directories. - - - - - Cleaning: - - - After the installation you can free disk space by removing the built - files from the source tree with the command make - clean. This will preserve the files made by the configure - program, so that you can rebuild everything with make - later on. To reset the source tree to the state in which it was - distributed, use make distclean. If you are going to - build for several platforms within the same source tree you must do - this and re-configure for each platform. (Alternatively, use - a separate build tree for each platform, so that the source tree - remains unmodified.) - - + - - If you perform a build and then discover that your configure - options were wrong, or if you change anything that configure - investigates (for example, software upgrades), then it's a good - idea to do make distclean before reconfiguring and - rebuilding. Without this, your changes in configuration choices - might not propagate everywhere they need to. -