Skip to content

P
Postgres FD Implementation
Commit 137b03b8 authored by Tom Lane's avatar Tom Lane
Browse files
Options

Doc: restructure documentation of the configure script's options. 

The list of configure options has grown long, and there was next
to no organization to it, never mind any indication of which options
were interesting to most people.  Break it into several sub-sections
to provide a bit of structure, and add some introductory text where
it seems helpful to point people to particular options.

I failed to resist the temptation to do a small amount of
word-smithing on some of the option descriptions, too.
But mostly this is reorganization and addition of intro text.

Discussion: https://postgr.es/m/6384.1559917369@sss.pgh.pa.us
parent 76c2af92
Hide whitespace changes
Inline Side-by-side
Showing with 664 additions and 495 deletions
doc/src/sgml/installation.sgml
View file @ 137b03b8
......@@ -327,12 +327,12 @@ su - postgres
<para>
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 <command>df</command> command to check free disk
300 MB. Use the <command>df</command> command to check free disk
space.
</para>
</sect1>
......@@ -351,8 +351,11 @@ su - postgres
<userinput>gunzip postgresql-&version;.tar.gz</userinput>
<userinput>tar xf postgresql-&version;.tar</userinput>
</screen>
(Use <command>bunzip2</command> instead of <command>gunzip</command> if you
have the <filename>.bz2</filename> file.)
(Use <command>bunzip2</command> instead of <command>gunzip</command> if
you have the <filename>.bz2</filename> file. Also, note that most
modern versions of <command>tar</command> can unpack compressed archives
directly, so you don't really need the
separate <command>gunzip</command> or <command>bunzip2</command> step.)
This will create a directory
<filename>postgresql-&version;</filename> under the current directory
with the <productname>PostgreSQL</productname> sources.
......@@ -389,10 +392,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
<filename>configure</filename> 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.
</para>
<para>
You can also run <filename>configure</filename> 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
<indexterm><primary>VPATH</primary></indexterm><firstterm>VPATH</firstterm>
build. Here's how:
<screen>
......@@ -412,8 +419,231 @@ su - postgres
<para>
You can customize the build and installation process by supplying one
or more of the following command line options to
<filename>configure</filename>:
or more command line options to <filename>configure</filename>.
Typically you would customize the install location, or the set of
optional features that are built. <filename>configure</filename>
has a large number of options, which are described in
<xref linkend="configure-options"/>.
</para>
<para>
Also, <filename>configure</filename> responds to certain environment
variables, as described in <xref linkend="configure-envvars"/>.
These provide additional ways to customize the configuration.
</para>
</step>
<step id="build">
<title>Build</title>
<para>
To start the build, type either of:
<screen>
<userinput>make</userinput>
<userinput>make all</userinput>
</screen>
(Remember to use <acronym>GNU</acronym> <application>make</application>.)
The build will take a few minutes depending on your
hardware. The last line displayed should be:
<screen>
All of PostgreSQL successfully made. Ready to install.
</screen>
</para>
<para>
If you want to build everything that can be built, including the
documentation (HTML and man pages), and the additional modules
(<filename>contrib</filename>), type instead:
<screen>
<userinput>make world</userinput>
</screen>
The last line displayed should be:
<screen>
PostgreSQL, contrib, and documentation successfully made. Ready to install.
</screen>
</para>
<para>
If you want to invoke the build from another makefile rather than
manually, you must unset <varname>MAKELEVEL</varname> or set it to zero,
for instance like this:
<programlisting>
build-postgresql:
$(MAKE) -C postgresql MAKELEVEL=0 all
</programlisting>
Failure to do that can lead to strange error messages, typically about
missing header files.
</para>
</step>
<step>
<title>Regression Tests</title>
<indexterm>
<primary>regression test</primary>
</indexterm>
<para>
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 <productname>PostgreSQL</productname>
runs on your machine in the way the developers expected it
to. Type:
<screen>
<userinput>make check</userinput>
</screen>
(This won't work as root; do it as an unprivileged user.)
See <xref linkend="regress"/> for
detailed information about interpreting the test results. You can
repeat this test at any later time by issuing the same command.
</para>
</step>
<step id="install">
<title>Installing the Files</title>
<note>
<para>
If you are upgrading an existing system be sure to read
<xref linkend="upgrading"/>,
which has instructions about upgrading a
cluster.
</para>
</note>
<para>
To install <productname>PostgreSQL</productname> enter:
<screen>
<userinput>make install</userinput>
</screen>
This will install files into the directories that were specified
in <xref linkend="configure"/>. 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.
</para>
<para>
To install the documentation (HTML and man pages), enter:
<screen>
<userinput>make install-docs</userinput>
</screen>
</para>
<para>
If you built the world above, type instead:
<screen>
<userinput>make install-world</userinput>
</screen>
This also installs the documentation.
</para>
<para>
You can use <literal>make install-strip</literal> instead of
<literal>make install</literal> 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. <literal>install-strip</literal>
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.
</para>
<para>
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 <productname>PostgreSQL</productname> 8.0, a separate <literal>make
install-all-headers</literal> command was needed for the latter, but this
step has been folded into the standard install.)
</para>
<formalpara>
<title>Client-only installation:</title>
<para>
If you want to install only the client applications and
interface libraries, then you can use these commands:
<screen>
<userinput>make -C src/bin install</userinput>
<userinput>make -C src/include install</userinput>
<userinput>make -C src/interfaces install</userinput>
<userinput>make -C doc install</userinput>
</screen>
<filename>src/bin</filename> has a few binaries for server-only use,
but they are small.
</para>
</formalpara>
</step>
</procedure>
<formalpara>
<title>Uninstallation:</title>
<para>
To undo the installation use the command <command>make
uninstall</command>. However, this will not remove any created directories.
</para>
</formalpara>
<formalpara>
<title>Cleaning:</title>
<para>
After the installation you can free disk space by removing the built
files from the source tree with the command <command>make
clean</command>. This will preserve the files made by the <command>configure</command>
program, so that you can rebuild everything with <command>make</command>
later on. To reset the source tree to the state in which it was
distributed, use <command>make distclean</command>. 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.)
</para>
</formalpara>
<para>
If you perform a build and then discover that your <command>configure</command>
options were wrong, or if you change anything that <command>configure</command>
investigates (for example, software upgrades), then it's a good
idea to do <command>make distclean</command> before reconfiguring and
rebuilding. Without this, your changes in configuration choices
might not propagate everywhere they need to.
</para>
<sect2 id="configure-options">
<title><filename>configure</filename> Options</title>
<indexterm zone="configure-options">
<primary>configure options</primary>
</indexterm>
<para>
<command>configure</command>'s command line options are explained below.
This list is not exhaustive (use <literal>./configure --help</literal>
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.
</para>
<sect3 id="configure-options-locations">
<title>Installation Locations</title>
<para>
These options control where <literal>make install</literal> will put
the files. The <option>--prefix</option> option is sufficient for
most cases. If you have special needs, you can customize the
installation 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 <literal>man</literal> and <literal>doc</literal> locations are
not affected by this restriction.) For relocatable installs, you
might want to use the <literal>--disable-rpath</literal> option
described later.
</para>
<variablelist>
<varlistentry>
......@@ -426,22 +656,6 @@ su - postgres
will ever be installed directly into the
<replaceable>PREFIX</replaceable> directory.
</para>
<para>
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 <literal>man</literal> and <literal>doc</literal>
locations are not affected by this.)
</para>
<para>
For relocatable installs, you might want to use
<filename>configure</filename>'s <literal>--disable-rpath</literal>
option. Also, you will need to tell the operating system how
to find the shared libraries.
</para>
</listitem>
</varlistentry>
......@@ -601,56 +815,21 @@ su - postgres
for dynamically loadable modules.
</para>
</note>
</para>
<para>
<variablelist>
<varlistentry>
<term><option>--with-extra-version=<replaceable>STRING</replaceable></option></term>
<listitem>
<para>
Append <replaceable>STRING</replaceable> 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 <command>git describe</command> identifier or a
distribution package release number.
</para>
</listitem>
</varlistentry>
</sect3>
<varlistentry>
<term><option>--with-includes=<replaceable>DIRECTORIES</replaceable></option></term>
<listitem>
<para>
<replaceable>DIRECTORIES</replaceable> 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 <application>Readline</application>) installed in a non-standard
location,
you have to use this option and probably also the corresponding
<option>--with-libraries</option> option.
</para>
<para>
Example: <literal>--with-includes=/opt/gnu/include:/usr/sup/include</literal>.
</para>
</listitem>
</varlistentry>
<sect3 id="configure-options-features">
<title><productname>PostgreSQL</productname> Features</title>
<varlistentry>
<term><option>--with-libraries=<replaceable>DIRECTORIES</replaceable></option></term>
<listitem>
<para>
<replaceable>DIRECTORIES</replaceable> is a colon-separated list of
directories to search for libraries. You will probably have
to use this option (and the corresponding
<option>--with-includes</option> option) if you have packages
installed in non-standard locations.
</para>
<para>
Example: <literal>--with-libraries=/opt/gnu/lib:/usr/sup/lib</literal>.
</para>
</listitem>
</varlistentry>
<para>
The options described in this section enable building of
various <productname>PostgreSQL</productname> features that are not
built by default. Most of these are non-default only because they
require additional software, as described in
<xref linkend="install-requirements"/>.
</para>
<variablelist>
<varlistentry>
<term><option>--enable-nls<optional>=<replaceable>LANGUAGES</replaceable></optional></option></term>
......@@ -670,22 +849,7 @@ su - postgres
<para>
To use this option, you will need an implementation of the
<application>Gettext</application> API; see above.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-pgport=<replaceable>NUMBER</replaceable></option></term>
<listitem>
<para>
Set <replaceable>NUMBER</replaceable> 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
<productname>PostgreSQL</productname> servers on the same machine.
<application>Gettext</application> API.
</para>
</listitem>
</varlistentry>
......@@ -726,38 +890,41 @@ su - postgres
interfacing to Tcl. This file is normally found automatically
at a well-known location, but if you want to use a different
version of Tcl you can specify the directory in which to look
for it.
for <filename>tclConfig.sh</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-gssapi</option></term>
<term><option>--with-icu</option></term>
<listitem>
<para>
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., <filename>/usr/include</filename>,
<filename>/usr/lib</filename>), so you must use the options
<option>--with-includes</option> and <option>--with-libraries</option> in
addition to this option. <filename>configure</filename> 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 <productname>ICU</productname><indexterm><primary>ICU</primary></indexterm>
library, enabling use of ICU collation
features<phrase condition="standalone-ignore"> (see
<xref linkend="collation"/>)</phrase>.
This requires the <productname>ICU4C</productname> package
to be installed. The minimum required version
of <productname>ICU4C</productname> is currently 4.2.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-krb-srvnam=<replaceable>NAME</replaceable></option></term>
<listitem>
<para>
The default name of the Kerberos service principal used
by GSSAPI.
<literal>postgres</literal> 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
<literal>POSTGRES</literal>.
By default,
<productname>pkg-config</productname><indexterm><primary>pkg-config</primary></indexterm>
will be used to find the required compilation options. This is
supported for <productname>ICU4C</productname> version 4.6 and later.
For older versions, or if <productname>pkg-config</productname> is
not available, the variables <envar>ICU_CFLAGS</envar>
and <envar>ICU_LIBS</envar> can be specified
to <filename>configure</filename>, like in this example:
<programlisting>
./configure ... --with-icu ICU_CFLAGS='-I/some/where/include' ICU_LIBS='-L/some/where/lib -licui18n -licuuc -licudata'
</programlisting>
(If <productname>ICU4C</productname> is in the default search path
for the compiler, then you still need to specify nonempty strings in
order to avoid use of <productname>pkg-config</productname>, for
example, <literal>ICU_CFLAGS=' '</literal>.)
</para>
</listitem>
</varlistentry>
......@@ -779,9 +946,10 @@ su - postgres
will be used to find the required compilation options.
<command>llvm-config</command>, and then
<command>llvm-config-$major-$minor</command> for all supported
versions, will be searched on <envar>PATH</envar>. If that would not
yield the correct binary, use <envar>LLVM_CONFIG</envar> to specify a
path to the correct <command>llvm-config</command>. For example
versions, will be searched for in your <envar>PATH</envar>. If
that would not yield the desired program,
use <envar>LLVM_CONFIG</envar> to specify a path to the
correct <command>llvm-config</command>. For example
<programlisting>
./configure ... --with-llvm LLVM_CONFIG='/path/to/llvm/bin/llvm-config'
</programlisting>
......@@ -797,37 +965,6 @@ su - postgres
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-icu</option></term>
<listitem>
<para>
Build with support for
the <productname>ICU</productname><indexterm><primary>ICU</primary></indexterm>
library. This requires the <productname>ICU4C</productname> package
to be installed. The minimum required version
of <productname>ICU4C</productname> is currently 4.2.
</para>
<para>
By default,
<productname>pkg-config</productname><indexterm><primary>pkg-config</primary></indexterm>
will be used to find the required compilation options. This is
supported for <productname>ICU4C</productname> version 4.6 and later.
For older versions, or if <productname>pkg-config</productname> is
not available, the variables <envar>ICU_CFLAGS</envar>
and <envar>ICU_LIBS</envar> can be specified
to <filename>configure</filename>, like in this example:
<programlisting>
./configure ... --with-icu ICU_CFLAGS='-I/some/where/include' ICU_LIBS='-L/some/where/lib -licui18n -licuuc -licudata'
</programlisting>
(If <productname>ICU4C</productname> is in the default search path
for the compiler, then you still need to specify a nonempty string in
order to avoid use of <productname>pkg-config</productname>, for
example, <literal>ICU_CFLAGS=' '</literal>.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-openssl</option>
<indexterm>
......@@ -848,22 +985,18 @@ su - postgres
</varlistentry>
<varlistentry>
<term><option>--with-pam</option></term>
<listitem>
<para>
Build with <acronym>PAM</acronym><indexterm><primary>PAM</primary></indexterm>
(Pluggable Authentication Modules) support.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-bsd-auth</option></term>
<term><option>--with-gssapi</option></term>
<listitem>
<para>
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., <filename>/usr/include</filename>,
<filename>/usr/lib</filename>), so you must use the options
<option>--with-includes</option> and <option>--with-libraries</option> in
addition to this option. <filename>configure</filename> will check
for the required header files and libraries to make sure that
your GSSAPI installation is sufficient before proceeding.
</para>
</listitem>
</varlistentry>
......@@ -887,41 +1020,37 @@ su - postgres
</varlistentry>
<varlistentry>
<term><option>--with-systemd</option></term>
<term><option>--with-pam</option></term>
<listitem>
<para>
Build with support
for <application>systemd</application><indexterm><primary>systemd</primary></indexterm>
service notifications. This improves integration if the server binary
is started under <application>systemd</application> but has no impact
otherwise<phrase condition="standalone-ignore">; see <xref linkend="server-start"/> for more
information</phrase>. <application>libsystemd</application> and the
associated header files need to be installed to be able to use this
option.
Build with <acronym>PAM</acronym><indexterm><primary>PAM</primary></indexterm>
(Pluggable Authentication Modules) support.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--without-readline</option></term>
<term><option>--with-bsd-auth</option></term>
<listitem>
<para>
Prevents use of the <application>Readline</application> library
(and <application>libedit</application> as well). This option disables
command-line editing and history in
<application>psql</application>, so it is not recommended.
Build with BSD Authentication support.
(The BSD Authentication framework is
currently only available on OpenBSD.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-libedit-preferred</option></term>
<term><option>--with-systemd</option></term>
<listitem>
<para>
Favors the use of the BSD-licensed <application>libedit</application> library
rather than GPL-licensed <application>Readline</application>. This option
is significant only if you have both libraries installed; the
default in that case is to use <application>Readline</application>.
Build with support
for <application>systemd</application><indexterm><primary>systemd</primary></indexterm>
service notifications. This improves integration if the server
is started under <application>systemd</application> but has no impact
otherwise<phrase condition="standalone-ignore">; see <xref linkend="server-start"/> for more
information</phrase>. <application>libsystemd</application> and the
associated header files need to be installed to use this option.
</para>
</listitem>
</varlistentry>
......@@ -930,8 +1059,9 @@ su - postgres
<term><option>--with-bonjour</option></term>
<listitem>
<para>
Build with Bonjour support. This requires Bonjour support
in your operating system. Recommended on macOS.
Build with support for Bonjour automatic service discovery.
This requires Bonjour support in your operating system.
Recommended on macOS.
</para>
</listitem>
</varlistentry>
......@@ -983,7 +1113,7 @@ su - postgres
<term><option>--with-libxml</option></term>
<listitem>
<para>
Build with libxml (enables SQL/XML support). Libxml version 2.6.23 or
Build with libxml, enabling SQL/XML support. Libxml version 2.6.23 or
later is required for this feature.
</para>
......@@ -1006,95 +1136,94 @@ su - postgres
<term><option>--with-libxslt</option></term>
<listitem>
<para>
Use libxslt when building the
Build with libxslt, enabling the
<xref linkend="xml2"/>
module. <application>xml2</application> relies on this library
to perform XSL transformations of XML.
module to perform XSL transformations of XML.
<option>--with-libxml</option> must be specified as well.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="configure-options-anti-features">
<title>Anti-Features</title>
<para>
The options described in this section allow disabling
certain <productname>PostgreSQL</productname> 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.
</para>
<variablelist>
<varlistentry>
<term><option>--disable-float4-byval</option></term>
<term><option>--without-readline</option></term>
<listitem>
<para>
Disable passing float4 values <quote>by value</quote>, causing them
to be passed <quote>by reference</quote> instead. This option costs
performance, but may be needed for compatibility with old
user-defined functions that are written in C and use the
<quote>version 0</quote> calling convention. A better long-term
solution is to update any such functions to use the
<quote>version 1</quote> calling convention.
Prevents use of the <application>Readline</application> library
(and <application>libedit</application> as well). This option disables
command-line editing and history in
<application>psql</application>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--disable-float8-byval</option></term>
<term><option>--with-libedit-preferred</option></term>
<listitem>
<para>
Disable passing float8 values <quote>by value</quote>, causing them
to be passed <quote>by reference</quote> instead. This option costs
performance, but may be needed for compatibility with old
user-defined functions that are written in C and use the
<quote>version 0</quote> calling convention. A better long-term
solution is to update any such functions to use the
<quote>version 1</quote> calling convention.
Note that this option affects not only float8, but also int8 and some
related types such as timestamp.
On 32-bit platforms, <option>--disable-float8-byval</option> is the default
and it is not allowed to select <option>--enable-float8-byval</option>.
Favors the use of the BSD-licensed <application>libedit</application> library
rather than GPL-licensed <application>Readline</application>. This option
is significant only if you have both libraries installed; the
default in that case is to use <application>Readline</application>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-segsize=<replaceable>SEGSIZE</replaceable></option></term>
<term><option>--without-zlib</option></term>
<listitem>
<para>
Set the <firstterm>segment size</firstterm>, 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
<quote>largefile</quote> 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 <application>tar</application>, 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.
<indexterm>
<primary>zlib</primary>
</indexterm>
Prevents use of the <application>Zlib</application> library.
This disables
support for compressed archives in <application>pg_dump</application>
and <application>pg_restore</application>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-blocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
<term><option>--disable-float4-byval</option></term>
<listitem>
<para>
Set the <firstterm>block size</firstterm>, 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 passing float4 values <quote>by value</quote>, causing them
to be passed <quote>by reference</quote> instead. This option costs
performance, but may be needed for compatibility with very old
user-defined functions written in C.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-wal-blocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
<term><option>--disable-float8-byval</option></term>
<listitem>
<para>
Set the <firstterm>WAL block size</firstterm>, 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 passing float8 values <quote>by value</quote>, causing them
to be passed <quote>by reference</quote> instead. This option costs
performance, but may be needed for compatibility with very old
user-defined functions written in C.
Note that this option affects not only float8, but also int8 and some
related types such as timestamp.
On 32-bit platforms, <option>--disable-float8-byval</option> is the default
and it is not allowed to select <option>--enable-float8-byval</option>.
</para>
</listitem>
</varlistentry>
......@@ -1105,7 +1234,7 @@ su - postgres
<para>
Allow the build to succeed even if <productname>PostgreSQL</productname>
has no CPU spinlock support for the platform. The lack of
spinlock support will result in poor performance; therefore,
spinlock support will result in very 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 <productname>PostgreSQL</productname> on
......@@ -1115,6 +1244,18 @@ su - postgres
</listitem>
</varlistentry>
<varlistentry>
<term><option>--disable-atomics</option></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--disable-thread-safety</option></term>
<listitem>
......@@ -1122,7 +1263,51 @@ su - postgres
Disable the thread-safety of client libraries. This prevents
concurrent threads in <application>libpq</application> and
<application>ECPG</application> programs from safely controlling
their private connection handles.
their private connection handles. Use this only on platforms
with deficient threading support.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="configure-options-build-process">
<title>Build Process Details</title>
<variablelist>
<varlistentry>
<term><option>--with-includes=<replaceable>DIRECTORIES</replaceable></option></term>
<listitem>
<para>
<replaceable>DIRECTORIES</replaceable> 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 <application>Readline</application>) installed in a non-standard
location,
you have to use this option and probably also the corresponding
<option>--with-libraries</option> option.
</para>
<para>
Example: <literal>--with-includes=/opt/gnu/include:/usr/sup/include</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-libraries=<replaceable>DIRECTORIES</replaceable></option></term>
<listitem>
<para>
<replaceable>DIRECTORIES</replaceable> is a colon-separated list of
directories to search for libraries. You will probably have
to use this option (and the corresponding
<option>--with-includes</option> option) if you have packages
installed in non-standard locations.
</para>
<para>
Example: <literal>--with-libraries=/opt/gnu/lib:/usr/sup/lib</literal>.
</para>
</listitem>
</varlistentry>
......@@ -1168,21 +1353,164 @@ su - postgres
</varlistentry>
<varlistentry>
<term><option>--without-zlib</option></term>
<term><option>--with-extra-version=<replaceable>STRING</replaceable></option></term>
<listitem>
<para>
<indexterm>
<primary>zlib</primary>
</indexterm>
Prevents use of the <application>Zlib</application> library. This disables
support for compressed archives in <application>pg_dump</application>
and <application>pg_restore</application>.
This option is only intended for those rare systems where this
library is not available.
Append <replaceable>STRING</replaceable> 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 <command>git describe</command> identifier or a
distribution package release number.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--disable-rpath</option></term>
<listitem>
<para>
Do not mark <productname>PostgreSQL</productname>'s executables
to indicate that they should search for shared libraries in the
installation's library directory (see <option>--libdir</option>).
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; see
<xref linkend="install-post-shlibs"/> for more detail.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="configure-options-misc">
<title>Miscellaneous</title>
<para>
It's fairly common, particularly for test builds, to adjust the
default port number with <option>--with-pgport</option>.
The other options in this section are recommended only for advanced
users.
</para>
<variablelist>
<varlistentry>
<term><option>--with-pgport=<replaceable>NUMBER</replaceable></option></term>
<listitem>
<para>
Set <replaceable>NUMBER</replaceable> 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
<productname>PostgreSQL</productname> servers on the same machine.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-krb-srvnam=<replaceable>NAME</replaceable></option></term>
<listitem>
<para>
The default name of the Kerberos service principal used
by GSSAPI.
<literal>postgres</literal> is the default. There's usually no
reason to change this unless you are building for a Windows
environment, in which case it must be set to upper case
<literal>POSTGRES</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-segsize=<replaceable>SEGSIZE</replaceable></option></term>
<listitem>
<para>
Set the <firstterm>segment size</firstterm>, 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
<quote>largefile</quote> 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 <application>tar</application>, 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 breaks on-disk database compatibility,
meaning you cannot use <command>pg_upgrade</command> to upgrade to
a build with a different segment size.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-blocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
<listitem>
<para>
Set the <firstterm>block size</firstterm>, 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 breaks on-disk database compatibility,
meaning you cannot use <command>pg_upgrade</command> to upgrade to
a build with a different block size.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-wal-blocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
<listitem>
<para>
Set the <firstterm>WAL block size</firstterm>, 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 breaks on-disk database compatibility,
meaning you cannot use <command>pg_upgrade</command> to upgrade to
a build with a different WAL block size.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="configure-options-devel">
<title>Developer Options</title>
<para>
Most of the options in this section are only of interest for
developing or debugging <productname>PostgreSQL</productname>.
They are not recommended for production builds, except
for <option>--enable-debug</option>, which can be useful to enable
detailed bug reports in the unlucky event that you encounter a bug.
On platforms supporting DTrace, <option>--enable-dtrace</option>
may also be reasonable to use in production.
</para>
<para>
When building an installation that will be used to develop code inside
the server, it is recommended to use at least the
options <option>--enable-debug</option>
and <option>--enable-cassert</option>.
</para>
<variablelist>
<varlistentry>
<term><option>--enable-debug</option></term>
<listitem>
......@@ -1201,6 +1529,50 @@ su - postgres
</listitem>
</varlistentry>
<varlistentry>
<term><option>--enable-cassert</option></term>
<listitem>
<para>
Enables <firstterm>assertion</firstterm> checks in the server, which test for
many <quote>cannot happen</quote> conditions. This is invaluable for
code development purposes, but the tests can slow down the
server significantly.
Also, having the tests turned on won't necessarily enhance the
stability of your server! The assertion checks are not categorized
for severity, and so what might be a relatively harmless bug will
still lead to server restarts if it triggers an assertion
failure. This option is not recommended for production use, but
you should have it on for development work or when running a beta
version.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--enable-tap-tests</option></term>
<listitem>
<para>
Enable tests using the Perl TAP tools. This requires a Perl
installation and the Perl module <literal>IPC::Run</literal>.
<phrase condition="standalone-ignore">See <xref linkend="regress-tap"/> for more information.</phrase>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--enable-depend</option></term>
<listitem>
<para>
Enables automatic dependency tracking. With this option, the
makefiles are set up so that all affected object files will
be rebuilt when any header file is changed. This is useful
if you are doing development work, but is just wasted overhead
if you intend only to compile once and install. At present,
this option only works with GCC.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--enable-coverage</option></term>
<listitem>
......@@ -1222,45 +1594,13 @@ su - postgres
<para>
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 <filename>gmon.out</filename> file for use in profiling.
that contains the <filename>gmon.out</filename> file containing
profile data.
This option is for use only with GCC and when doing development work.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--enable-cassert</option></term>
<listitem>
<para>
Enables <firstterm>assertion</firstterm> checks in the server, which test for
many <quote>cannot happen</quote> conditions. This is invaluable for
code development purposes, but the tests can slow down the
server significantly.
Also, having the tests turned on won't necessarily enhance the
stability of your server! The assertion checks are not categorized
for severity, and so what might be a relatively harmless bug will
still lead to server restarts if it triggers an assertion
failure. This option is not recommended for production use, but
you should have it on for development work or when running a beta
version.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--enable-depend</option></term>
<listitem>
<para>
Enables automatic dependency tracking. With this option, the
makefiles are set up so that all affected object files will
be rebuilt when any header file is changed. This is useful
if you are doing development work, but is just wasted overhead
if you intend only to compile once and install. At present,
this option only works with GCC.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--enable-dtrace</option></term>
<listitem>
......@@ -1279,7 +1619,7 @@ su - postgres
environment variable <envar>DTRACE</envar> can be set. This
will often be necessary because <command>dtrace</command> is
typically installed under <filename>/usr/sbin</filename>,
which might not be in the path.
which might not be in your <envar>PATH</envar>.
</para>
<para>
......@@ -1287,7 +1627,7 @@ su - postgres
can be specified in the environment variable
<envar>DTRACEFLAGS</envar>. On Solaris,
to include DTrace support in a 64-bit binary, you must specify
<literal>DTRACEFLAGS="-64"</literal> to configure. For example,
<literal>DTRACEFLAGS="-64"</literal>. For example,
using the GCC compiler:
<screen>
./configure CC='gcc -m64' --enable-dtrace DTRACEFLAGS='-64' ...
......@@ -1299,38 +1639,52 @@ su - postgres
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--enable-tap-tests</option></term>
<listitem>
<para>
Enable tests using the Perl TAP tools. This requires a Perl
installation and the Perl module <literal>IPC::Run</literal>.
<phrase condition="standalone-ignore">See <xref linkend="regress-tap"/> for more information.</phrase>
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect2>
<sect2 id="configure-envvars">
<title><filename>configure</filename> Environment Variables</title>
<indexterm zone="configure-envvars">
<primary>configure environment variables</primary>
</indexterm>
<para>
In addition to the ordinary command-line options described above,
<filename>configure</filename> responds to a number of environment
variables.
You can specify environment variables on the
<filename>configure</filename> command line, for example:
<screen>
<userinput>./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'</userinput>
</screen>
In this usage an environment variable is little different from a
command-line option.
You can also set such variables beforehand:
<screen>
<userinput>export CC=/opt/bin/gcc</userinput>
<userinput>export CFLAGS='-O2 -pipe'</userinput>
<userinput>./configure</userinput>
</screen>
This usage can be convenient because many programs' configuration
scripts respond to these variables in similar ways.
</para>
<para>
The most commonly used of these environment variables are
<envar>CC</envar> and <envar>CFLAGS</envar>.
If you prefer a C compiler different from the one
<filename>configure</filename> picks, you can set the
environment variable <envar>CC</envar> to the program of your choice.
variable <envar>CC</envar> to the program of your choice.
By default, <filename>configure</filename> will pick
<filename>gcc</filename> if available, else the platform's
default (usually <filename>cc</filename>). Similarly, you can override the
default compiler flags if needed with the <envar>CFLAGS</envar> variable.
</para>
<para>
You can specify environment variables on the
<filename>configure</filename> command line, for example:
<screen>
<userinput>./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'</userinput>
</screen>
</para>
<para>
Here is a list of the significant variables that can be set in
this manner:
......@@ -1468,7 +1822,7 @@ su - postgres
<listitem>
<para>
<command>llvm-config</command> program used to locate the
<productname>LLVM</productname> installation.
<productname>LLVM</productname> installation
</para>
</listitem>
</varlistentry>
......@@ -1514,8 +1868,10 @@ su - postgres
<listitem>
<para>
Tcl interpreter program. This will be used to
determine the dependencies for building PL/Tcl, and it will
be substituted into Tcl scripts.
determine the dependencies for building PL/Tcl.
If this is not set, the following are probed in this
order: <literal>tclsh tcl tclsh8.6 tclsh86 tclsh8.5 tclsh85
tclsh8.4 tclsh84</literal>.
</para>
</listitem>
</varlistentry>
......@@ -1525,7 +1881,7 @@ su - postgres
<listitem>
<para>
<command>xml2-config</command> program used to locate the
libxml installation.
libxml installation
</para>
</listitem>
</varlistentry>
......@@ -1553,13 +1909,6 @@ su - postgres
</para>
<note>
<para>
When developing code inside the server, it is recommended to
use the configure options <option>--enable-cassert</option> (which
turns on many run-time error checks) and <option>--enable-debug</option>
(which improves the usefulness of debugging tools).
</para>
<para>
If using GCC, it is best to build with an optimization level of
at least <option>-O1</option>, because using no optimization
......@@ -1581,193 +1930,13 @@ su - postgres
adjustments, while <envar>COPT</envar> might be kept set all the time.
</para>
</note>
</step>
<step id="build">
<title>Build</title>
<para>
To start the build, type either of:
<screen>
<userinput>make</userinput>
<userinput>make all</userinput>
</screen>
(Remember to use <acronym>GNU</acronym> <application>make</application>.)
The build will take a few minutes depending on your
hardware. The last line displayed should be:
<screen>
All of PostgreSQL successfully made. Ready to install.
</screen>
</para>
<para>
If you want to build everything that can be built, including the
documentation (HTML and man pages), and the additional modules
(<filename>contrib</filename>), type instead:
<screen>
<userinput>make world</userinput>
</screen>
The last line displayed should be:
<screen>
PostgreSQL, contrib, and documentation successfully made. Ready to install.
</screen>
</para>
<para>
If you want to invoke the build from another makefile rather than
manually, you must unset <varname>MAKELEVEL</varname> or set it to zero,
for instance like this:
<programlisting>
build-postgresql:
$(MAKE) -C postgresql MAKELEVEL=0 all
</programlisting>
Failure to do that can lead to strange error messages, typically about
missing header files.
</para>
</step>
<step>
<title>Regression Tests</title>
<indexterm>
<primary>regression test</primary>
</indexterm>
<para>
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 <productname>PostgreSQL</productname>
runs on your machine in the way the developers expected it
to. Type:
<screen>
<userinput>make check</userinput>
</screen>
(This won't work as root; do it as an unprivileged user.)
See <xref linkend="regress"/> for
detailed information about interpreting the test results. You can
repeat this test at any later time by issuing the same command.
</para>
</step>
<step id="install">
<title>Installing the Files</title>
<note>
<para>
If you are upgrading an existing system be sure to read
<xref linkend="upgrading"/>,
which has instructions about upgrading a
cluster.
</para>
</note>
<para>
To install <productname>PostgreSQL</productname> enter:
<screen>
<userinput>make install</userinput>
</screen>
This will install files into the directories that were specified
in <xref linkend="configure"/>. 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.
</para>
<para>
To install the documentation (HTML and man pages), enter:
<screen>
<userinput>make install-docs</userinput>
</screen>
</para>
<para>
If you built the world above, type instead:
<screen>
<userinput>make install-world</userinput>
</screen>
This also installs the documentation.
</para>
<para>
You can use <literal>make install-strip</literal> instead of
<literal>make install</literal> 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. <literal>install-strip</literal>
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.
</para>
<para>
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 <productname>PostgreSQL</productname> 8.0, a separate <literal>make
install-all-headers</literal> command was needed for the latter, but this
step has been folded into the standard install.)
</para>
<formalpara>
<title>Client-only installation:</title>
<para>
If you want to install only the client applications and
interface libraries, then you can use these commands:
<screen>
<userinput>make -C src/bin install</userinput>
<userinput>make -C src/include install</userinput>
<userinput>make -C src/interfaces install</userinput>
<userinput>make -C doc install</userinput>
</screen>
<filename>src/bin</filename> has a few binaries for server-only use,
but they are small.
</para>
</formalpara>
</step>
</procedure>
<formalpara>
<title>Uninstallation:</title>
<para>
To undo the installation use the command <command>make
uninstall</command>. However, this will not remove any created directories.
</para>
</formalpara>
<formalpara>
<title>Cleaning:</title>
<para>
After the installation you can free disk space by removing the built
files from the source tree with the command <command>make
clean</command>. This will preserve the files made by the <command>configure</command>
program, so that you can rebuild everything with <command>make</command>
later on. To reset the source tree to the state in which it was
distributed, use <command>make distclean</command>. 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.)
</para>
</formalpara>
<para>
If you perform a build and then discover that your <command>configure</command>
options were wrong, or if you change anything that <command>configure</command>
investigates (for example, software upgrades), then it's a good
idea to do <command>make distclean</command> before reconfiguring and
rebuilding. Without this, your changes in configuration choices
might not propagate everywhere they need to.
</para>
</sect2>
</sect1>
<sect1 id="install-post">
<title>Post-Installation Setup</title>
<sect2>
<sect2 id="install-post-shlibs">
<title>Shared Libraries</title>
<indexterm>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment