doc/src/sgml/installation.sgml

   1 <!-- $PostgreSQL$ -->
   2
   3 <chapter id="installation">
   4  <title><![%standalone-include[<productname>PostgreSQL</>]]>
   5   Installation Instructions</title>
   6
   7  <indexterm zone="installation">
   8   <primary>installation</primary>
   9  </indexterm>
  10
  11  <para>
  12   This <![%standalone-include;[document]]>
  13   <![%standalone-ignore;[chapter]]> describes the installation of
  14   <productname>PostgreSQL</productname> from the source code
  15   distribution.  (If you are installing a pre-packaged distribution,
  16   such as an RPM or Debian package, ignore this
  17   <![%standalone-include;[document]]>
  18   <![%standalone-ignore;[chapter]]>
  19   and read the packager's instructions instead.)
  20  </para>
  21
  22  <sect1 id="install-short">
  23   <title>Short Version</title>
  24
  25   <para>
  26 <synopsis>
  27 ./configure
  28 gmake
  29 su
  30 gmake install
  31 adduser postgres
  32 mkdir /usr/local/pgsql/data
  33 chown postgres /usr/local/pgsql/data
  34 su - postgres
  35 /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
  36 /usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data &gt;logfile 2&gt;&amp;1 &amp;
  37 /usr/local/pgsql/bin/createdb test
  38 /usr/local/pgsql/bin/psql test
  39 </synopsis>
  40    The long version is the rest of this
  41    <![%standalone-include;[document.]]>
  42    <![%standalone-ignore;[chapter.]]>
  43   </para>
  44  </sect1>
  45
  46
  47  <sect1 id="install-requirements">
  48   <title>Requirements</title>
  49
  50   <para>
  51    In general, a modern Unix-compatible platform should be able to run
  52    <productname>PostgreSQL</>.
  53    The platforms that had received specific testing at the
  54    time of release are listed in <xref linkend="supported-platforms">
  55    below. In the <filename>doc</> subdirectory of the distribution
  56    there are several platform-specific <acronym>FAQ</> documents you
  57    might wish to consult if you are having trouble.
  58   </para>
  59
  60   <para>
  61    The following software packages are required for building
  62    <productname>PostgreSQL</>:
  63
  64    <itemizedlist>
  65     <listitem>
  66      <para>
  67       <indexterm>
  68        <primary>make</primary>
  69       </indexterm>
  70
  71       <acronym>GNU</> <application>make</> is required; other
  72       <application>make</> programs will <emphasis>not</> work.
  73       <acronym>GNU</> <application>make</> is often installed under
  74       the name <filename>gmake</filename>; this document will always
  75       refer to it by that name. (On some systems
  76       <acronym>GNU</acronym> <application>make</> is the default tool with the name
  77       <filename>make</>.) To test for <acronym>GNU</acronym>
  78       <application>make</application> enter
  79 <screen>
  80 <userinput>gmake --version</userinput>
  81 </screen>
  82       It is recommended to use version 3.76.1 or later.
  83      </para>
  84     </listitem>
  85
  86     <listitem>
  87      <para>
  88       You need an <acronym>ISO</>/<acronym>ANSI</> C compiler. Recent
  89       versions of <productname>GCC</> are recommendable, but
  90       <productname>PostgreSQL</> is known to build with a wide variety
  91       of compilers from different vendors.
  92      </para>
  93     </listitem>
  94
  95     <listitem>
  96      <para>
  97       <application>tar</> is required to unpack the source
  98       distribution in the first place, in addition to either
  99       <application>gzip</> or <application>bzip2</>.
 100      </para>
 101     </listitem>
 102
 103     <listitem>
 104      <para>
 105       <indexterm>
 106        <primary>readline</primary>
 107       </indexterm>
 108       <indexterm>
 109        <primary>libedit</primary>
 110       </indexterm>
 111
 112       The <acronym>GNU</> <productname>Readline</> library (for
 113       simple line editing and command history retrieval) is
 114       used by default. If you don't want to use it then you must specify
 115       the <option>--without-readline</option> option for
 116       <filename>configure</>. As an alternative, you can often use the
 117       BSD-licensed <filename>libedit</filename> library, originally
 118       developed on <productname>NetBSD</productname>. The
 119       <filename>libedit</filename> library is
 120       GNU <productname>Readline</productname>-compatible and is used if
 121       <filename>libreadline</filename> is not found, or if
 122       <option>--with-libedit-preferred</option> is used as an
 123       option to <filename>configure</>. If you are using a package-based
 124       Linux distribution, be aware that you need both the
 125       <literal>readline</> and <literal>readline-devel</> packages, if
 126       those are separate in your distribution.
 127      </para>
 128     </listitem>
 129
 130     <listitem>
 131      <para>
 132       <indexterm>
 133        <primary>zlib</primary>
 134       </indexterm>
 135
 136       The <productname>zlib</productname> compression library will be
 137       used by default. If you don't want to use it then you must
 138       specify the <option>--without-zlib</option> option for
 139       <filename>configure</filename>. Using this option disables
 140       support for compressed archives in <application>pg_dump</> and
 141       <application>pg_restore</>.
 142      </para>
 143     </listitem>
 144    </itemizedlist>
 145   </para>
 146
 147   <para>
 148    The following packages are optional.  They are not required in the
 149    default configuration, but they are needed when certain build
 150    options are enabled, as explained below.
 151
 152    <itemizedlist>
 153     <listitem>
 154      <para>
 155       To build the server programming language
 156       <application>PL/Perl</application> you need a full
 157       <productname>Perl</productname> installation, including the
 158       <filename>libperl</filename> library and the header files.
 159       Since <application>PL/Perl</application> will be a shared
 160       library, the <indexterm><primary>libperl</primary></indexterm>
 161       <filename>libperl</filename> library must be a shared library
 162       also on most platforms.  This appears to be the default in
 163       recent <productname>Perl</productname> versions, but it was not
 164       in earlier versions, and in any case it is the choice of whomever
 165       installed Perl at your site.
 166      </para>
 167
 168      <para>
 169       If you don't have the shared library but you need one, a message
 170       like this will appear during the build to point out this fact:
 171 <screen>
 172 *** Cannot build PL/Perl because libperl is not a shared library.
 173 *** You might have to rebuild your Perl installation.  Refer to
 174 *** the documentation for details.
 175 </screen>
 176       (If you don't follow the on-screen output you will merely notice
 177       that the <application>PL/Perl</application> library object,
 178       <filename>plperl.so</filename> or similar, will not be
 179       installed.)  If you see this, you will have to rebuild and
 180       install <productname>Perl</productname> manually to be able to
 181       build <application>PL/Perl</application>.  During the
 182       configuration process for <productname>Perl</productname>,
 183       request a shared library.
 184      </para>
 185     </listitem>
 186
 187     <listitem>
 188      <para>
 189       To build the <application>PL/Python</> server programming
 190       language, you need a <productname>Python</productname>
 191       installation with the header files and the <application>distutils</application> module.
 192       The <application>distutils</application> module is included by default with
 193       <productname>Python</productname> 1.6 and later; users of
 194       earlier versions of <productname>Python</productname> will need
 195       to install it.
 196      </para>
 197
 198      <para>
 199       Since <application>PL/Python</application> will be a shared
 200       library, the <indexterm><primary>libpython</primary></indexterm>
 201       <filename>libpython</filename> library must be a shared library
 202       also on most platforms.  This is not the case in a default
 203       <productname>Python</productname> installation.  If after
 204       building and installing you have a file called
 205       <filename>plpython.so</filename> (possibly a different
 206       extension), then everything went well.  Otherwise you should
 207       have seen a notice like this flying by:
 208 <screen>
 209 *** Cannot build PL/Python because libpython is not a shared library.
 210 *** You might have to rebuild your Python installation.  Refer to
 211 *** the documentation for details.
 212 </screen>
 213       That means you have to rebuild (part of) your
 214       <productname>Python</productname> installation to supply this
 215       shared library.
 216      </para>
 217
 218      <para>
 219       If you have problems, run <productname>Python</> 2.3 or later's
 220       configure using the <literal>--enable-shared</> flag.  On some
 221       operating systems you don't have to build a shared library, but
 222       you will have to convince the <productname>PostgreSQL</> build
 223       system of this.  Consult the <filename>Makefile</filename> in
 224       the <filename>src/pl/plpython</filename> directory for details.
 225      </para>
 226     </listitem>
 227
 228     <listitem>
 229      <para>
 230       If you want to build the <application>PL/Tcl</application>
 231       procedural language, you of course need a <productname>Tcl</>
 232       installation.  If you are using a pre-8.4 release of
 233       <productname>Tcl</>, ensure that it was built without multithreading
 234       support.
 235      </para>
 236     </listitem>
 237
 238     <listitem>
 239      <para>
 240       To enable Native Language Support (<acronym>NLS</acronym>), that
 241       is, the ability to display a program's messages in a language
 242       other than English, you need an implementation of the
 243       <application>Gettext</> <acronym>API</acronym>.  Some operating
 244       systems have this built-in (e.g., <systemitem
 245       class="osname">Linux</>, <systemitem class="osname">NetBSD</>,
 246       <systemitem class="osname">Solaris</>), for other systems you
 247       can download an add-on package from <ulink
 248       url="http://developer.postgresql.org/~petere/bsd-gettext/"></ulink>.
 249       If you are using the <application>Gettext</> implementation in
 250       the <acronym>GNU</acronym> C library then you will additionally
 251       need the <productname>GNU Gettext</productname> package for some
 252       utility programs.  For any of the other implementations you will
 253       not need it.
 254      </para>
 255     </listitem>
 256
 257     <listitem>
 258      <para>
 259       <application>Kerberos</>, <productname>OpenSSL</>,
 260       <productname>OpenLDAP</>, and/or
 261       <application>PAM</>, if you want to support authentication or
 262       encryption using these services.
 263      </para>
 264     </listitem>
 265    </itemizedlist>
 266   </para>
 267
 268   <para>
 269    If you are building from a <acronym>CVS</acronym> tree instead of
 270    using a released source package, or if you want to do development,
 271    you also need the following packages:
 272
 273    <itemizedlist>
 274     <listitem>
 275      <para>
 276       <indexterm>
 277        <primary>flex</primary>
 278       </indexterm>
 279       <indexterm>
 280        <primary>bison</primary>
 281       </indexterm>
 282       <indexterm>
 283        <primary>yacc</primary>
 284       </indexterm>
 285
 286       GNU <application>Flex</> and <application>Bison</>
 287       are needed to build a CVS checkout or if you changed the actual
 288       scanner and parser definition files. If you need them, be sure
 289       to get <application>Flex</> 2.5.4 or later and
 290       <application>Bison</> 1.875 or later. Other <application>yacc</>
 291       programs can sometimes be used, but doing so requires extra
 292       effort and is not recommended. Other <application>lex</>
 293       programs will definitely not work.
 294      </para>
 295     </listitem>
 296    </itemizedlist>
 297   </para>
 298
 299   <para>
 300    If you need to get a <acronym>GNU</acronym> package, you can find
 301    it at your local <acronym>GNU</acronym> mirror site (see <ulink
 302    url="http://www.gnu.org/order/ftp.html"></>
 303    for a list) or at <ulink
 304    url="ftp://ftp.gnu.org/gnu/"></ulink>.
 305   </para>
 306
 307   <para>
 308    Also check that you have sufficient disk space. You will need about
 309    65 MB for the source tree during compilation and about 15 MB for
 310    the installation directory. An empty database cluster takes about
 311    25 MB, databases take about five times the amount of space that a
 312    flat text file with the same data would take. If you are going to
 313    run the regression tests you will temporarily need up to an extra
 314    90 MB. Use the <command>df</command> command to check free disk
 315    space.
 316   </para>
 317  </sect1>
 318
 319 <![%standalone-ignore;[
 320  <sect1 id="install-getsource">
 321   <title>Getting The Source</title>
 322
 323   <para>
 324    The <productname>PostgreSQL</> &version; sources can be obtained by
 325    anonymous FTP from <ulink
 326    url="ftp://ftp.postgresql.org/pub/source/v&version;/postgresql-&version;.tar.gz"></ulink>.
 327    Other download options can be found on our website:
 328    <ulink url="http://www.postgresql.org/download/"></ulink>. After you
 329    have obtained the file, unpack it:
 330 <screen>
 331 <userinput>gunzip postgresql-&version;.tar.gz</userinput>
 332 <userinput>tar xf postgresql-&version;.tar</userinput>
 333 </screen>
 334    This will create a directory
 335    <filename>postgresql-&version;</filename> under the current directory
 336    with the <productname>PostgreSQL</> sources.
 337    Change into that directory for the rest
 338    of the installation procedure.
 339   </para>
 340  </sect1>
 341 ]]>
 342
 343  <sect1 id="install-upgrading">
 344   <title>Upgrading</title>
 345
 346   <indexterm zone="install-upgrading">
 347    <primary>upgrading</primary>
 348   </indexterm>
 349
 350   <para>
 351    These instructions assume that your existing installation is under the
 352    <filename>/usr/local/pgsql</> directory, and that the data area is in
 353    <filename>/usr/local/pgsql/data</>.  Substitute your paths
 354    appropriately.
 355   </para>
 356
 357   <para>
 358    The internal data storage format typically changes in every major
 359    release of <productname>PostgreSQL</>. Therefore, if you are upgrading
 360    an existing installation that does not have a version number of
 361    <quote>&majorversion;.x</quote>, you must back up and restore your
 362    data.  If you are upgrading from <productname>PostgreSQL</>
 363    <quote>&majorversion;.x</quote>, the new version can use your current
 364    data files so you should skip the backup and restore steps below because
 365    they are unnecessary.
 366   </para>
 367
 368   <procedure>
 369    <step>
 370     <para>
 371      If making a backup, make sure that your database is not being updated.
 372      This does not affect the integrity of the backup, but the changed
 373      data would of course not be included. If necessary, edit the
 374      permissions in the file <filename>/usr/local/pgsql/data/pg_hba.conf</>
 375      (or equivalent) to disallow access from everyone except you.
 376     </para>
 377
 378     <para>
 379      <indexterm>
 380       <primary>pg_dumpall</primary>
 381       <secondary>use during upgrade</secondary>
 382      </indexterm>
 383
 384      To back up your database installation, type:
 385 <screen>
 386 <userinput>pg_dumpall &gt; <replaceable>outputfile</></userinput>
 387 </screen>
 388      If you need to preserve OIDs (such as when using them as
 389      foreign keys), then use the <option>-o</option> option when running
 390      <application>pg_dumpall</>.
 391     </para>
 392
 393     <para>
 394      To make the backup, you can use the <application>pg_dumpall</application>
 395      command from the version you are currently running.  For best
 396      results, however, try to use the <application>pg_dumpall</application>
 397      command from <productname>PostgreSQL</productname> &version;,
 398      since this version contains bug fixes and improvements over older
 399      versions.  While this advice might seem idiosyncratic since you
 400      haven't installed the new version yet, it is advisable to follow
 401      it if you plan to install the new version in parallel with the
 402      old version.  In that case you can complete the installation
 403      normally and transfer the data later.  This will also decrease
 404      the downtime.
 405     </para>
 406    </step>
 407
 408    <step>
 409     <para>
 410      Shut down the old server:
 411 <screen>
 412 <userinput>pg_ctl stop</>
 413 </screen>
 414      On systems that have <productname>PostgreSQL</> started at boot time,
 415      there is probably a start-up file that will accomplish the same thing. For
 416      example, on a <systemitem class="osname">Red Hat Linux</> system one
 417      might find that
 418 <screen>
 419 <userinput>/etc/rc.d/init.d/postgresql stop</userinput>
 420 </screen>
 421      works.
 422     </para>
 423    </step>
 424
 425    <step>
 426     <para>
 427      If restoring from backup, rename or delete the old installation
 428      directory.  It is a good idea to rename the directory, rather than
 429      delete it, in case you have trouble and need to revert to it.  Keep
 430      in mind the directory might consume significant disk space.  To rename
 431      the directory, use a command like this:
 432 <screen>
 433 <userinput>mv /usr/local/pgsql /usr/local/pgsql.old</>
 434 </screen>
 435     </para>
 436    </step>
 437
 438    <step>
 439     <para>
 440      Install the new version of <productname>PostgreSQL</productname> as
 441      outlined in <![%standalone-include[the next section.]]>
 442      <![%standalone-ignore[<xref linkend="install-procedure">.]]>
 443     </para>
 444    </step>
 445
 446    <step>
 447     <para>
 448      Create a new database cluster if needed.  Remember that you must
 449      execute these commands while logged in to the special database user
 450      account (which you already have if you are upgrading).
 451 <programlisting>
 452 <userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</>
 453 </programlisting>
 454     </para>
 455    </step>
 456
 457    <step>
 458     <para>
 459      Restore your previous <filename>pg_hba.conf</> and any
 460      <filename>postgresql.conf</> modifications.
 461     </para>
 462    </step>
 463
 464    <step>
 465     <para>
 466      Start the database server, again from the special database user
 467      account:
 468 <programlisting>
 469 <userinput>/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data</>
 470 </programlisting>
 471     </para>
 472    </step>
 473
 474    <step>
 475     <para>
 476      Finally, restore your data from backup with
 477 <screen>
 478 <userinput>/usr/local/pgsql/bin/psql -d postgres -f <replaceable>outputfile</></userinput>
 479 </screen>
 480      using the <emphasis>new</> <application>psql</>.
 481     </para>
 482    </step>
 483   </procedure>
 484
 485   <para>
 486    Further discussion appears in
 487    <![%standalone-include[the documentation,]]>
 488    <![%standalone-ignore[<xref linkend="migration">,]]>
 489    including instructions on how the previous installation can continue
 490    running while the new installation is installed.
 491   </para>
 492  </sect1>
 493
 494
 495  <sect1 id="install-procedure">
 496   <title>Installation Procedure</title>
 497
 498   <procedure>
 499
 500   <step id="configure">
 501    <title>Configuration</>
 502
 503    <indexterm zone="configure">
 504     <primary>configure</primary>
 505    </indexterm>
 506
 507    <para>
 508     The first step of the installation procedure is to configure the
 509     source tree for your system and choose the options you would like.
 510     This is done by running the <filename>configure</> script. For a
 511     default installation simply enter
 512 <screen>
 513 <userinput>./configure</userinput>
 514 </screen>
 515     This script will run a number of tests to guess values for various
 516     system dependent variables and detect some quirks of your
 517     operating system, and finally will create several files in the
 518     build tree to record what it found.  (You can also run
 519     <filename>configure</filename> in a directory outside the source
 520     tree if you want to keep the build directory separate.)
 521    </para>
 522
 523    <para>
 524     The default configuration will build the server and utilities, as
 525     well as all client applications and interfaces that require only a
 526     C compiler. All files will be installed under
 527     <filename>/usr/local/pgsql</> by default.
 528    </para>
 529
 530    <para>
 531     You can customize the build and installation process by supplying one
 532     or more of the following command line options to
 533     <filename>configure</filename>:
 534
 535      <variablelist>
 536       <varlistentry>
 537        <term><option>--prefix=<replaceable>PREFIX</></option></term>
 538        <listitem>
 539         <para>
 540          Install all files under the directory <replaceable>PREFIX</>
 541          instead of <filename>/usr/local/pgsql</filename>. The actual
 542          files will be installed into various subdirectories; no files
 543          will ever be installed directly into the
 544          <replaceable>PREFIX</> directory.
 545         </para>
 546
 547         <para>
 548          If you have special needs, you can also customize the
 549          individual subdirectories with the following options. However,
 550          if you leave these with their defaults, the installation will be
 551          relocatable, meaning you can move the directory after
 552          installation. (The <literal>man</> and <literal>doc</>
 553          locations are not affected by this.)
 554         </para>
 555
 556         <para>
 557          For relocatable installs, you might want to use
 558          <filename>configure</filename>'s <literal>--disable-rpath</>
 559          option.  Also, you will need to tell the operating system how
 560          to find the shared libraries.
 561         </para>
 562        </listitem>
 563       </varlistentry>
 564
 565       <varlistentry>
 566        <term><option>--exec-prefix=<replaceable>EXEC-PREFIX</></option></term>
 567        <listitem>
 568         <para>
 569          You can install architecture-dependent files under a
 570          different prefix, <replaceable>EXEC-PREFIX</>, than what
 571          <replaceable>PREFIX</> was set to. This can be useful to
 572          share architecture-independent files between hosts. If you
 573          omit this, then <replaceable>EXEC-PREFIX</> is set equal to
 574          <replaceable>PREFIX</> and both architecture-dependent and
 575          independent files will be installed under the same tree,
 576          which is probably what you want.
 577         </para>
 578        </listitem>
 579       </varlistentry>
 580
 581       <varlistentry>
 582        <term><option>--bindir=<replaceable>DIRECTORY</></option></term>
 583        <listitem>
 584         <para>
 585          Specifies the directory for executable programs. The default
 586          is <filename><replaceable>EXEC-PREFIX</>/bin</>, which
 587          normally means <filename>/usr/local/pgsql/bin</>.
 588         </para>
 589        </listitem>
 590       </varlistentry>
 591
 592       <varlistentry>
 593        <term><option>--sysconfdir=<replaceable>DIRECTORY</></option></term>
 594        <listitem>
 595         <para>
 596          Sets the directory for various configuration files,
 597          <filename><replaceable>PREFIX</>/etc</> by default.
 598         </para>
 599        </listitem>
 600       </varlistentry>
 601
 602       <varlistentry>
 603        <term><option>--libdir=<replaceable>DIRECTORY</></option></term>
 604        <listitem>
 605         <para>
 606          Sets the location to install libraries and dynamically loadable
 607          modules. The default is
 608          <filename><replaceable>EXEC-PREFIX</>/lib</>.
 609         </para>
 610        </listitem>
 611       </varlistentry>
 612
 613       <varlistentry>
 614        <term><option>--includedir=<replaceable>DIRECTORY</></option></term>
 615        <listitem>
 616         <para>
 617          Sets the directory for installing C and C++ header files. The
 618          default is <filename><replaceable>PREFIX</>/include</>.
 619         </para>
 620        </listitem>
 621       </varlistentry>
 622
 623       <varlistentry>
 624        <term><option>--datarootdir=<replaceable>DIRECTORY</></option></term>
 625        <listitem>
 626         <para>
 627          Sets the root directory for various types of read-only data
 628          files.  This only sets the default for some of the following
 629          options.  The default is
 630          <filename><replaceable>PREFIX</>/share</>.
 631         </para>
 632        </listitem>
 633       </varlistentry>
 634
 635       <varlistentry>
 636        <term><option>--datadir=<replaceable>DIRECTORY</></option></term>
 637        <listitem>
 638         <para>
 639          Sets the directory for read-only data files used by the
 640          installed programs. The default is
 641          <filename><replaceable>DATAROOTDIR</></>. Note that this has
 642          nothing to do with where your database files will be placed.
 643         </para>
 644        </listitem>
 645       </varlistentry>
 646
 647       <varlistentry>
 648        <term><option>--localedir=<replaceable>DIRECTORY</></option></term>
 649        <listitem>
 650         <para>
 651          Sets the directory for installing locale data, in particular
 652          message translation catalog files.  The default is
 653          <filename><replaceable>DATAROOTDIR</>/locale</>.
 654         </para>
 655        </listitem>
 656       </varlistentry>
 657
 658       <varlistentry>
 659        <term><option>--mandir=<replaceable>DIRECTORY</></option></term>
 660        <listitem>
 661         <para>
 662          The man pages that come with <productname>PostgreSQL</> will be installed under
 663          this directory, in their respective
 664          <filename>man<replaceable>x</></> subdirectories.
 665          The default is <filename><replaceable>DATAROOTDIR</>/man</>.
 666         </para>
 667        </listitem>
 668       </varlistentry>
 669
 670       <varlistentry>
 671        <term><option>--docdir=<replaceable>DIRECTORY</></option></term>
 672        <listitem>
 673         <para>
 674          Sets the root directory for installing documentation files,
 675          except <quote>man</> pages.  This only sets the default for
 676          the following options.  The default value for this option is
 677          <filename><replaceable>DATAROOTDIR</>/doc/postgresql</>.
 678         </para>
 679        </listitem>
 680       </varlistentry>
 681
 682       <varlistentry>
 683        <term><option>--htmldir=<replaceable>DIRECTORY</></option></term>
 684        <listitem>
 685         <para>
 686          The HTML-formatted documentation for
 687          <productname>PostgreSQL</productname> will be installed under
 688          this directory.  The default is
 689          <filename><replaceable>DATAROOTDIR</></>.
 690         </para>
 691        </listitem>
 692       </varlistentry>
 693      </variablelist>
 694
 695      <note>
 696       <para>
 697        Care has been taken to make it possible to install
 698        <productname>PostgreSQL</> into shared installation locations
 699        (such as <filename>/usr/local/include</filename>) without
 700        interfering with the namespace of the rest of the system. First,
 701        the string <quote><literal>/postgresql</literal></quote> is
 702        automatically appended to <varname>datadir</varname>,
 703        <varname>sysconfdir</varname>, and <varname>docdir</varname>,
 704        unless the fully expanded directory name already contains the
 705        string <quote><literal>postgres</></quote> or
 706        <quote><literal>pgsql</></quote>. For example, if you choose
 707        <filename>/usr/local</filename> as prefix, the documentation will
 708        be installed in <filename>/usr/local/doc/postgresql</filename>,
 709        but if the prefix is <filename>/opt/postgres</filename>, then it
 710        will be in <filename>/opt/postgres/doc</filename>. The public C
 711        header files of the client interfaces are installed into
 712        <varname>includedir</varname> and are namespace-clean. The
 713        internal header files and the server header files are installed
 714        into private directories under <varname>includedir</varname>. See
 715        the documentation of each interface for information about how to
 716        get at the its header files. Finally, a private subdirectory will
 717        also be created, if appropriate, under <varname>libdir</varname>
 718        for dynamically loadable modules.
 719       </para>
 720      </note>
 721     </para>
 722
 723     <para>
 724      <variablelist>
 725       <varlistentry>
 726        <term><option>--with-includes=<replaceable>DIRECTORIES</></option></term>
 727        <listitem>
 728         <para>
 729          <replaceable>DIRECTORIES</> is a colon-separated list of
 730          directories that will be added to the list the compiler
 731          searches for header files. If you have optional packages
 732          (such as GNU <application>Readline</>) installed in a non-standard
 733          location,
 734          you have to use this option and probably also the corresponding
 735          <option>--with-libraries</> option.
 736         </para>
 737         <para>
 738          Example: <literal>--with-includes=/opt/gnu/include:/usr/sup/include</>.
 739         </para>
 740        </listitem>
 741       </varlistentry>
 742
 743       <varlistentry>
 744        <term><option>--with-libraries=<replaceable>DIRECTORIES</></option></term>
 745        <listitem>
 746         <para>
 747          <replaceable>DIRECTORIES</> is a colon-separated list of
 748          directories to search for libraries. You will probably have
 749          to use this option (and the corresponding
 750          <option>--with-includes</> option) if you have packages
 751          installed in non-standard locations.
 752         </para>
 753         <para>
 754          Example: <literal>--with-libraries=/opt/gnu/lib:/usr/sup/lib</>.
 755         </para>
 756        </listitem>
 757       </varlistentry>
 758
 759       <varlistentry>
 760        <term><option>--enable-nls<optional>=<replaceable>LANGUAGES</replaceable></optional></option></term>
 761        <listitem>
 762         <para>
 763          Enables Native Language Support (<acronym>NLS</acronym>),
 764          that is, the ability to display a program's messages in a
 765          language other than English.
 766          <replaceable>LANGUAGES</replaceable> is a space-separated
 767          list of codes of the languages that you want supported, for
 768          example <literal>--enable-nls='de fr'</>.  (The intersection
 769          between your list and the set of actually provided
 770          translations will be computed automatically.)  If you do not
 771          specify a list, then all available translations are
 772          installed.
 773         </para>
 774
 775         <para>
 776          To use this option, you will need an implementation of the
 777          <application>Gettext</> API; see above.
 778         </para>
 779        </listitem>
 780       </varlistentry>
 781
 782       <varlistentry>
 783        <term><option>--with-pgport=<replaceable>NUMBER</></option></term>
 784        <listitem>
 785         <para>
 786          Set <replaceable>NUMBER</> as the default port number for
 787          server and clients. The default is 5432. The port can always
 788          be changed later on, but if you specify it here then both
 789          server and clients will have the same default compiled in,
 790          which can be very convenient.  Usually the only good reason
 791          to select a non-default value is if you intend to run multiple
 792          <productname>PostgreSQL</> servers on the same machine.
 793         </para>
 794        </listitem>
 795       </varlistentry>
 796
 797       <varlistentry>
 798        <term><option>--with-perl</option></term>
 799        <listitem>
 800         <para>
 801          Build the <application>PL/Perl</> server-side language.
 802         </para>
 803        </listitem>
 804       </varlistentry>
 805
 806       <varlistentry>
 807        <term><option>--with-python</option></term>
 808        <listitem>
 809         <para>
 810          Build the <application>PL/Python</> server-side language.
 811         </para>
 812        </listitem>
 813       </varlistentry>
 814
 815       <varlistentry>
 816        <term><option>--with-tcl</option></term>
 817        <listitem>
 818         <para>
 819          Build the <application>PL/Tcl</> server-side language.
 820         </para>
 821        </listitem>
 822       </varlistentry>
 823
 824       <varlistentry>
 825        <term><option>--with-tclconfig=<replaceable>DIRECTORY</replaceable></option></term>
 826        <listitem>
 827         <para>
 828          Tcl installs the file <filename>tclConfig.sh</filename>, which
 829          contains configuration information needed to build modules
 830          interfacing to Tcl. This file is normally found automatically
 831          at a well-known location, but if you want to use a different
 832          version of Tcl you can specify the directory in which to look
 833          for it.
 834         </para>
 835        </listitem>
 836       </varlistentry>
 837
 838       <varlistentry>
 839        <term><option>--with-gssapi</option></term>
 840        <listitem>
 841         <para>
 842          Build with support for GSSAPI authentication. On many
 843          systems, the GSSAPI (usually a part of the Kerberos installation)
 844          system is not installed in a location
 845          that is searched by default (e.g., <filename>/usr/include</>,
 846          <filename>/usr/lib</>), so you must use the options
 847          <option>--with-includes</> and <option>--with-libraries</> in
 848          addition to this option.  <filename>configure</> will check
 849          for the required header files and libraries to make sure that
 850          your GSSAPI installation is sufficient before proceeding.
 851         </para>
 852        </listitem>
 853       </varlistentry>
 854
 855       <varlistentry>
 856        <term><option>--with-krb5</option></term>
 857        <listitem>
 858         <para>
 859          Build with support for Kerberos 5 authentication. On many
 860          systems, the Kerberos system is not installed in a location
 861          that is searched by default (e.g., <filename>/usr/include</>,
 862          <filename>/usr/lib</>), so you must use the options
 863          <option>--with-includes</> and <option>--with-libraries</> in
 864          addition to this option.  <filename>configure</> will check
 865          for the required header files and libraries to make sure that
 866          your Kerberos installation is sufficient before proceeding.
 867         </para>
 868        </listitem>
 869       </varlistentry>
 870
 871       <varlistentry>
 872        <term><option>--with-krb-srvnam=<replaceable>NAME</></option></term>
 873        <listitem>
 874         <para>
 875          The default name of the Kerberos service principal (also used
 876          by GSSAPI).
 877          <literal>postgres</literal> is the default. There's usually no
 878          reason to change this unless you have a Windows environment,
 879          in which case it must be set to uppercase
 880          <literal>POSTGRES</literal>.
 881         </para>
 882        </listitem>
 883       </varlistentry>
 884
 885       <varlistentry>
 886        <indexterm>
 887         <primary>OpenSSL</primary>
 888         <seealso>SSL</seealso>
 889        </indexterm>
 890
 891        <term><option>--with-openssl</option></term>
 892        <listitem>
 893         <para>
 894          Build with support for <acronym>SSL</> (encrypted)
 895          connections. This requires the <productname>OpenSSL</>
 896          package to be installed.  <filename>configure</> will check
 897          for the required header files and libraries to make sure that
 898          your <productname>OpenSSL</> installation is sufficient
 899          before proceeding.
 900         </para>
 901        </listitem>
 902       </varlistentry>
 903
 904       <varlistentry>
 905        <term><option>--with-pam</option></term>
 906        <listitem>
 907         <para>
 908          Build with <acronym>PAM</><indexterm><primary>PAM</></>
 909          (Pluggable Authentication Modules) support.
 910         </para>
 911        </listitem>
 912       </varlistentry>
 913
 914       <varlistentry>
 915        <term><option>--with-ldap</option></term>
 916        <listitem>
 917         <para>
 918          Build with <acronym>LDAP</><indexterm><primary>LDAP</></>
 919          support for authentication and connection parameter lookup (see
 920          <![%standalone-include[the documentation about client authentication
 921          and libpq]]><![%standalone-ignore[<xref linkend="libpq-ldap"> and
 922          <xref linkend="auth-ldap">]]> for more information). On Unix,
 923          this requires the <productname>OpenLDAP</> package to be
 924          installed. <filename>configure</> will check for the required
 925          header files and libraries to make sure that your
 926          <productname>OpenLDAP</> installation is sufficient before
 927          proceeding. On Windows, the default <productname>WinLDAP</>
 928          library is used.
 929         </para>
 930        </listitem>
 931       </varlistentry>
 932
 933       <varlistentry>
 934        <term><option>--without-readline</option></term>
 935        <listitem>
 936         <para>
 937          Prevents use of the <application>Readline</> library
 938          (and <application>libedit</> as well).  This option disables
 939          command-line editing and history in
 940          <application>psql</application>, so it is not recommended.
 941         </para>
 942        </listitem>
 943       </varlistentry>
 944
 945       <varlistentry>
 946        <term><option>--with-libedit-preferred</option></term>
 947        <listitem>
 948         <para>
 949          Favors the use of the BSD-licensed <application>libedit</> library
 950          rather than GPL-licensed <application>Readline</>.  This option
 951          is significant only if you have both libraries installed; the
 952          default in that case is to use <application>Readline</>.
 953         </para>
 954        </listitem>
 955       </varlistentry>
 956
 957       <varlistentry>
 958        <term><option>--with-bonjour</option></term>
 959        <listitem>
 960         <para>
 961          Build with Bonjour support.  This requires Bonjour support
 962          in your operating system.  Recommended on Mac OS X.
 963         </para>
 964        </listitem>
 965       </varlistentry>
 966
 967       <varlistentry>
 968        <term><option>--with-ossp-uuid</option></term>
 969        <listitem>
 970         <para>
 971          Use the <ulink url="http://www.ossp.org/pkg/lib/uuid/">OSSP UUID
 972          library</ulink> when building <filename>contrib/uuid-ossp</>.
 973          The library provides functions to generate
 974          UUIDs.<indexterm><primary>UUID</primary></indexterm>
 975         </para>
 976        </listitem>
 977       </varlistentry>
 978
 979       <varlistentry>
 980        <term><option>--with-libxml</option></term>
 981        <listitem>
 982         <para>
 983          Build with libxml (enables SQL/XML support).  Libxml version 2.6.23 or
 984          later is required for this feature.
 985         </para>
 986
 987         <para>
 988          Libxml installs a program <command>xml2-config</command> that
 989          can be used to detect the required compiler and linker
 990          options.  PostgreSQL will use it automatically if found.  To
 991          specify a libxml installation at an unusual location, you can
 992          either set the environment variable
 993          <envar>XML2_CONFIG</envar> to point to the
 994          <command>xml2-config</command> program belonging to the
 995          installation, or use the options
 996          <option>--with-includes</option> and
 997          <option>--with-libraries</option>.
 998         </para>
 999        </listitem>
1000       </varlistentry>
1001
1002       <varlistentry>
1003        <term><option>--with-libxslt</option></term>
1004        <listitem>
1005         <para>
1006          Use libxslt when building <filename>contrib/xml2</>.
1007          <filename>contrib/xml2</> relies on this library to perform
1008          XSL transformations of XML.
1009         </para>
1010        </listitem>
1011       </varlistentry>
1012
1013       <varlistentry>
1014        <term><option>--disable-integer-datetimes</option></term>
1015        <listitem>
1016         <para>
1017          Disable support for 64-bit integer storage for timestamps and
1018          intervals, and store datetime values as floating-point
1019          numbers instead. Floating-point datetime storage was the
1020          default in <productname>PostgreSQL</productname> releases
1021          prior to 8.4, but it is now deprecated, because it does not
1022          support microsecond precision for the full range of
1023          <type>timestamp</type> values. However, integer-based
1024          datetime storage requires a 64-bit integer type. Therefore,
1025          this option can be used when no such type is available, or
1026          for compatibility with applications written for prior
1027          versions of <productname>PostgreSQL</productname>. See
1028          <![%standalone-include[the documentation about datetime datatypes]]>
1029          <![%standalone-ignore[<xref linkend="datatype-datetime">]]>
1030          for more information.
1031         </para>
1032        </listitem>
1033       </varlistentry>
1034
1035       <varlistentry>
1036        <term><option>--disable-float4-byval</option></term>
1037        <listitem>
1038         <para>
1039          Disable passing float4 values <quote>by value</>, causing them
1040          to be passed <quote>by reference</> instead.  This option costs
1041          performance, but may be needed for compatibility with old
1042          user-defined functions that are written in C and use the
1043          <quote>version 0</> calling convention.  A better long-term
1044          solution is to update any such functions to use the
1045          <quote>version 1</> calling convention.
1046         </para>
1047        </listitem>
1048       </varlistentry>
1049
1050       <varlistentry>
1051        <term><option>--disable-float8-byval</option></term>
1052        <listitem>
1053         <para>
1054          Disable passing float8 values <quote>by value</>, causing them
1055          to be passed <quote>by reference</> instead.  This option costs
1056          performance, but may be needed for compatibility with old
1057          user-defined functions that are written in C and use the
1058          <quote>version 0</> calling convention.  A better long-term
1059          solution is to update any such functions to use the
1060          <quote>version 1</> calling convention.
1061          Note that this option affects not only float8, but also int8 and some
1062          related types such as timestamp.
1063          On 32-bit platforms, <option>--disable-float8-byval</> is the default
1064          and it is not allowed to select <option>--enable-float8-byval</>.
1065         </para>
1066        </listitem>
1067       </varlistentry>
1068
1069       <varlistentry>
1070        <term><option>--with-segsize=<replaceable>SEGSIZE</replaceable></option></term>
1071        <listitem>
1072         <para>
1073          Set the <firstterm>segment size</>, in gigabytes.  Large tables are
1074          divided into multiple operating-system files, each of size equal
1075          to the segment size.  This avoids problems with file size limits
1076          that exist on many platforms.  The default segment size, 1 gigabyte,
1077          is safe on all supported platforms.  If your operating system has
1078          <quote>largefile</> support (which most do, nowadays), you can use
1079          a larger segment size.  This can be helpful to reduce the number of
1080          file descriptors consumed when working with very large tables.
1081          But be careful not to select a value larger than is supported
1082          by your platform and the filesystem(s) you intend to use.  Other
1083          tools you might wish to use, such as <application>tar</>, could
1084          also set limits on the usable file size.
1085          It is recommended, though not absolutely required, that this value
1086          be a power of 2.
1087          Note that changing this value requires an initdb.
1088         </para>
1089        </listitem>
1090       </varlistentry>
1091
1092       <varlistentry>
1093        <term><option>--with-blocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
1094        <listitem>
1095         <para>
1096          Set the <firstterm>block size</>, in kilobytes.  This is the unit
1097          of storage and I/O within tables.  The default, 8 kilobytes,
1098          is suitable for most situations; but other values may be useful
1099          in special cases.
1100          The value must be a power of 2 between 1 and 32 (kilobytes).
1101          Note that changing this value requires an initdb.
1102         </para>
1103        </listitem>
1104       </varlistentry>
1105
1106       <varlistentry>
1107        <term><option>--with-wal-segsize=<replaceable>SEGSIZE</replaceable></option></term>
1108        <listitem>
1109         <para>
1110          Set the <firstterm>WAL segment size</>, in megabytes.  This is
1111          the size of each individual file in the WAL log.  It may be useful
1112          to adjust this size to control the granularity of WAL log shipping.
1113          The default size is 16 megabytes.
1114          The value must be a power of 2 between 1 and 64 (megabytes).
1115          Note that changing this value requires an initdb.
1116         </para>
1117        </listitem>
1118       </varlistentry>
1119
1120       <varlistentry>
1121        <term><option>--with-wal-blocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
1122        <listitem>
1123         <para>
1124          Set the <firstterm>WAL block size</>, in kilobytes.  This is the unit
1125          of storage and I/O within the WAL log.  The default, 8 kilobytes,
1126          is suitable for most situations; but other values may be useful
1127          in special cases.
1128          The value must be a power of 2 between 1 and 64 (kilobytes).
1129          Note that changing this value requires an initdb.
1130         </para>
1131        </listitem>
1132       </varlistentry>
1133
1134       <varlistentry>
1135        <term><option>--disable-spinlocks</option></term>
1136        <listitem>
1137         <para>
1138          Allow the build to succeed even if <productname>PostgreSQL</>
1139          has no CPU spinlock support for the platform.  The lack of
1140          spinlock support will result in poor performance; therefore,
1141          this option should only be used if the build aborts and
1142          informs you that the platform lacks spinlock support. If this
1143          option is required to build <productname>PostgreSQL</> on
1144          your platform, please report the problem to the
1145          <productname>PostgreSQL</> developers.
1146         </para>
1147        </listitem>
1148       </varlistentry>
1149
1150       <varlistentry>
1151        <term><option>--enable-thread-safety</option></term>
1152        <listitem>
1153         <para>
1154          Make the client libraries thread-safe.  This allows
1155          concurrent threads in <application>libpq</application> and
1156          <application>ECPG</application> programs to safely control
1157          their private connection handles.  This option requires adequate
1158          threading support in your operating system.
1159         </para>
1160        </listitem>
1161       </varlistentry>
1162
1163       <varlistentry>
1164        <term><option>--with-system-tzdata=<replaceable>DIRECTORY</replaceable></option></term>
1165        <indexterm>
1166         <primary>time zone data</primary>
1167        </indexterm>
1168        <listitem>
1169         <para>
1170          <productname>PostgreSQL</> includes its own time zone database,
1171          which it requires for date and time operations.  This time zone
1172          database is in fact compatible with the <quote>zoneinfo</> time zone
1173          database provided by many operating systems such as FreeBSD,
1174          Linux, and Solaris, so it would be redundant to install it again.
1175          When this option is used, the system-supplied time zone database
1176          in <replaceable>DIRECTORY</replaceable> is used instead of the one
1177          included in the PostgreSQL source distribution.
1178          <replaceable>DIRECTORY</replaceable> must be specified as an
1179          absolute path.  <filename>/usr/share/zoneinfo</filename> is a
1180          likely directory on some operating systems.  Note that the
1181          installation routine will not detect mismatching or erroneous time
1182          zone data.  If you use this option, you are advised to run the
1183          regression tests to verify that the time zone data you have
1184          pointed to works correctly with <productname>PostgreSQL</>.
1185         </para>
1186
1187         <para>
1188          This option is mainly aimed at binary package distributors
1189          who know their target operating system well.  The main
1190          advantage of using this option is that the PostgreSQL package
1191          won't need to be upgraded whenever any of the many local
1192          daylight-saving time rules change.  Another advantage is that
1193          PostgreSQL can be cross-compiled<indexterm><primary>cross
1194          compilation</primary></indexterm> more straightforwardly if the
1195          time zone database files do not need to be built during the
1196          installation.
1197         </para>
1198        </listitem>
1199       </varlistentry>
1200
1201       <varlistentry>
1202        <term><option>--without-zlib</option></term>
1203        <listitem>
1204         <para>
1205          <indexterm>
1206           <primary>zlib</primary>
1207          </indexterm>
1208          Prevents use of the <application>Zlib</> library.  This disables
1209          support for compressed archives in <application>pg_dump</application>
1210          and <application>pg_restore</application>.
1211          This option is only intended for those rare systems where this
1212          library is not available.
1213         </para>
1214        </listitem>
1215       </varlistentry>
1216
1217       <varlistentry>
1218        <term><option>--enable-debug</option></term>
1219        <listitem>
1220         <para>
1221          Compiles all programs and libraries with debugging symbols.
1222          This means that you can run the programs through a debugger
1223          to analyze problems. This enlarges the size of the installed
1224          executables considerably, and on non-GCC compilers it usually
1225          also disables compiler optimization, causing slowdowns. However,
1226          having the symbols available is extremely helpful for dealing
1227          with any problems that might arise.  Currently, this option is
1228          recommended for production installations only if you use GCC.
1229          But you should always have it on if you are doing development work
1230          or running a beta version.
1231         </para>
1232        </listitem>
1233       </varlistentry>
1234
1235       <varlistentry>
1236        <term><option>--enable-profiling</option></term>
1237        <listitem>
1238         <para>
1239          If using GCC, all programs and libraries are compiled so they
1240          can be profiled.  On backend exit, a subdirectory will be created
1241          that contains the <filename>gmon.out</> file for use in profiling.
1242          This option is for use only with GCC and when doing development work.
1243         </para>
1244        </listitem>
1245       </varlistentry>
1246
1247       <varlistentry>
1248        <term><option>--enable-cassert</option></term>
1249        <listitem>
1250         <para>
1251          Enables <firstterm>assertion</> checks in the server, which test for
1252          many <quote>cannot happen</> conditions.  This is invaluable for
1253          code development purposes, but the tests can slow down the
1254          server significantly.
1255          Also, having the tests turned on won't necessarily enhance the
1256          stability of your server!  The assertion checks are not categorized
1257          for severity, and so what might be a relatively harmless bug will
1258          still lead to server restarts if it triggers an assertion
1259          failure.  This option is not recommended for production use, but
1260          you should have it on for development work or when running a beta
1261          version.
1262         </para>
1263        </listitem>
1264       </varlistentry>
1265
1266       <varlistentry>
1267        <term><option>--enable-depend</option></term>
1268        <listitem>
1269         <para>
1270          Enables automatic dependency tracking.  With this option, the
1271          makefiles are set up so that all affected object files will
1272          be rebuilt when any header file is changed.  This is useful
1273          if you are doing development work, but is just wasted overhead
1274          if you intend only to compile once and install.  At present,
1275          this option will work only if you use GCC.
1276         </para>
1277        </listitem>
1278       </varlistentry>
1279
1280       <varlistentry>
1281        <term><option>--enable-dtrace</option></term>
1282        <listitem>
1283         <para>
1284          <indexterm>
1285           <primary>DTrace</primary>
1286          </indexterm>
1287          Compiles with support for the dynamic tracing tool DTrace.
1288          Operating system support for DTrace is currently available in
1289          Solaris and Mac OS X Leopard.
1290         </para>
1291
1292         <para>
1293          To point to the <command>dtrace</command> program, the
1294          environment variable <envar>DTRACE</envar> can be set.  This
1295          will often be necessary because <command>dtrace</command> is
1296          typically installed under <filename>/usr/sbin</filename>,
1297          which might not be in the path.  Additional command-line
1298          options for the <command>dtrace</command> program can be
1299          specified in the environment variable
1300          <envar>DTRACEFLAGS</envar>.
1301         </para>
1302
1303         <para>
1304          To include DTrace support in a 64-bit binary, specify
1305          <literal>DTRACEFLAGS="-64"</> to configure.  For example,
1306          using the GCC compiler:
1307 <screen>
1308 ./configure CC='gcc -m64' --enable-dtrace DTRACEFLAGS='-64' ...
1309 </screen>
1310          Using Sun's compiler:
1311 <screen>
1312 ./configure CC='/opt/SUNWspro/bin/cc -xtarget=native64' --enable-dtrace DTRACEFLAGS='-64' ...
1313 </screen>
1314         </para>
1315        </listitem>
1316       </varlistentry>
1317
1318      </variablelist>
1319     </para>
1320
1321     <para>
1322      If you prefer a C compiler different from the one
1323      <filename>configure</filename> picks, you can set the
1324      environment variable <envar>CC</> to the program of your choice.
1325      By default, <filename>configure</filename> will pick
1326      <filename>gcc</filename> if available, else the platform's
1327      default (usually <filename>cc</>).  Similarly, you can override the
1328      default compiler flags if needed with the <envar>CFLAGS</envar> variable.
1329     </para>
1330
1331     <para>
1332      You can specify environment variables on the
1333      <filename>configure</filename> command line, for example:
1334 <screen>
1335 <userinput>./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'</>
1336 </screen>
1337     </para>
1338
1339     <para>
1340      Here is a list of the significant variables that can be set in
1341      this manner:
1342
1343      <variablelist>
1344       <varlistentry>
1345        <term><envar>CC</envar></term>
1346        <listitem>
1347         <para>
1348          C compiler
1349         </para>
1350        </listitem>
1351       </varlistentry>
1352
1353       <varlistentry>
1354        <term><envar>CFLAGS</envar></term>
1355        <listitem>
1356         <para>
1357          options to pass to the C compiler
1358         </para>
1359        </listitem>
1360       </varlistentry>
1361
1362       <varlistentry>
1363        <term><envar>CPP</envar></term>
1364        <listitem>
1365         <para>
1366          C preprocessor
1367         </para>
1368        </listitem>
1369       </varlistentry>
1370
1371       <varlistentry>
1372        <term><envar>CPPFLAGS</envar></term>
1373        <listitem>
1374         <para>
1375          options to pass to the C preprocessor
1376         </para>
1377        </listitem>
1378       </varlistentry>
1379
1380       <varlistentry>
1381        <term><envar>DTRACE</envar></term>
1382        <listitem>
1383         <para>
1384          location of the <command>dtrace</command> program
1385         </para>
1386        </listitem>
1387       </varlistentry>
1388
1389       <varlistentry>
1390        <term><envar>DTRACEFLAGS</envar></term>
1391        <listitem>
1392         <para>
1393          options to pass to the <command>dtrace</command> program
1394         </para>
1395        </listitem>
1396       </varlistentry>
1397
1398       <varlistentry>
1399        <term><envar>LDFLAGS</envar></term>
1400        <listitem>
1401         <para>
1402          options to pass to the link editor
1403         </para>
1404        </listitem>
1405       </varlistentry>
1406
1407       <varlistentry>
1408        <term><envar>LDFLAGS_SL</envar></term>
1409        <listitem>
1410         <para>
1411          linker options for shared library linking
1412         </para>
1413        </listitem>
1414       </varlistentry>
1415
1416       <varlistentry>
1417        <term><envar>MSGFMT</envar></term>
1418        <listitem>
1419         <para>
1420          <command>msgfmt</command> program for native language support
1421         </para>
1422        </listitem>
1423       </varlistentry>
1424
1425       <varlistentry>
1426        <term><envar>PERL</envar></term>
1427        <listitem>
1428         <para>
1429          Full path to the Perl interpreter.  This will be used to
1430          determine the dependencies for building PL/Perl.
1431         </para>
1432        </listitem>
1433       </varlistentry>
1434
1435       <varlistentry>
1436        <term><envar>PYTHON</envar></term>
1437        <listitem>
1438         <para>
1439          Full path to the Python interpreter.  This will be used to
1440          determine the dependencies for building PL/Python.
1441         </para>
1442        </listitem>
1443       </varlistentry>
1444
1445       <varlistentry>
1446        <term><envar>TCLSH</envar></term>
1447        <listitem>
1448         <para>
1449          Full path to the Tcl interpreter.  This will be used to
1450          determine the dependencies for building PL/Tcl.
1451         </para>
1452        </listitem>
1453       </varlistentry>
1454
1455       <varlistentry>
1456        <term><envar>XML2_CONFIG</envar></term>
1457        <listitem>
1458         <para>
1459          <command>xml2-config</command> program used to locate the
1460          libxml installation.
1461         </para>
1462        </listitem>
1463       </varlistentry>
1464
1465       <varlistentry>
1466        <term><envar>YACC</envar></term>
1467        <listitem>
1468         <para>
1469          Yacc program (<literal>bison -y</literal> if using Bison)
1470         </para>
1471        </listitem>
1472       </varlistentry>
1473      </variablelist>
1474     </para>
1475    </step>
1476
1477   <step>
1478    <title>Build</title>
1479
1480    <para>
1481     To start the build, type
1482 <screen>
1483 <userinput>gmake</userinput>
1484 </screen>
1485     (Remember to use <acronym>GNU</> <application>make</>.) The build
1486     will take a few minutes depending on your
1487     hardware. The last line displayed should be
1488 <screen>
1489 All of PostgreSQL is successfully made. Ready to install.
1490 </screen>
1491    </para>
1492   </step>
1493
1494   <step>
1495    <title>Regression Tests</title>
1496
1497    <indexterm>
1498     <primary>regression test</primary>
1499    </indexterm>
1500
1501    <para>
1502     If you want to test the newly built server before you install it,
1503     you can run the regression tests at this point. The regression
1504     tests are a test suite to verify that <productname>PostgreSQL</>
1505     runs on your machine in the way the developers expected it
1506     to. Type
1507 <screen>
1508 <userinput>gmake check</userinput>
1509 </screen>
1510     (This won't work as root; do it as an unprivileged user.)
1511     <![%standalone-include[The file
1512     <filename>src/test/regress/README</> and the
1513     documentation contain]]>
1514     <![%standalone-ignore[<xref linkend="regress"> contains]]>
1515     detailed information about interpreting the test results. You can
1516     repeat this test at any later time by issuing the same command.
1517    </para>
1518   </step>
1519
1520   <step id="install">
1521    <title>Installing The Files</title>
1522
1523    <note>
1524     <para>
1525      If you are upgrading an existing system and are going to install
1526      the new files over the old ones, be sure to back up
1527      your data and shut down the old server before proceeding, as explained in
1528      <xref linkend="install-upgrading"> above.
1529     </para>
1530    </note>
1531
1532    <para>
1533     To install <productname>PostgreSQL</> enter
1534 <screen>
1535 <userinput>gmake install</userinput>
1536 </screen>
1537     This will install files into the directories that were specified
1538     in <xref linkend="configure">. Make sure that you have appropriate
1539     permissions to write into that area. Normally you need to do this
1540     step as root. Alternatively, you could create the target
1541     directories in advance and arrange for appropriate permissions to
1542     be granted.
1543    </para>
1544
1545    <para>
1546     You can use <literal>gmake install-strip</literal> instead of
1547     <literal>gmake install</literal> to strip the executable files and
1548     libraries as they are installed.  This will save some space.  If
1549     you built with debugging support, stripping will effectively
1550     remove the debugging support, so it should only be done if
1551     debugging is no longer needed.  <literal>install-strip</literal>
1552     tries to do a reasonable job saving space, but it does not have
1553     perfect knowledge of how to strip every unneeded byte from an
1554     executable file, so if you want to save all the disk space you
1555     possibly can, you will have to do manual work.
1556    </para>
1557
1558    <para>
1559     The standard installation provides all the header files needed for client
1560     application development as well as for server-side program
1561     development, such as custom functions or data types written in C.
1562     (Prior to <productname>PostgreSQL</> 8.0, a separate <literal>gmake
1563     install-all-headers</> command was needed for the latter, but this
1564     step has been folded into the standard install.)
1565    </para>
1566
1567    <formalpara>
1568     <title>Client-only installation:</title>
1569     <para>
1570      If you want to install only the client applications and
1571      interface libraries, then you can use these commands:
1572 <screen>
1573 <userinput>gmake -C src/bin install</>
1574 <userinput>gmake -C src/include install</>
1575 <userinput>gmake -C src/interfaces install</>
1576 <userinput>gmake -C doc install</>
1577 </screen>
1578     <filename>src/bin</> has a few binaries for server-only use,
1579     but they are small.
1580     </para>
1581    </formalpara>
1582   </step>
1583   </procedure>
1584
1585   <formalpara>
1586    <title>Registering <application>eventlog</> on <systemitem
1587    class="osname">Windows</>:</title>
1588    <para>
1589     To register a <systemitem class="osname">Windows</> <application>eventlog</>
1590     library with the operating system, issue this command after installation:
1591 <screen>
1592 <userinput>regsvr32 <replaceable>pgsql_library_directory</>/pgevent.dll</>
1593 </screen>
1594     This creates registry entries used by the event viewer.
1595    </para>
1596   </formalpara>
1597
1598   <formalpara>
1599    <title>Uninstallation:</title>
1600    <para>
1601     To undo the installation use the command <command>gmake
1602     uninstall</>. However, this will not remove any created directories.
1603    </para>
1604   </formalpara>
1605
1606   <formalpara>
1607    <title>Cleaning:</title>
1608
1609    <para>
1610     After the installation you can make room by removing the built
1611     files from the source tree with the command <command>gmake
1612     clean</>. This will preserve the files made by the <command>configure</command>
1613     program, so that you can rebuild everything with <command>gmake</>
1614     later on. To reset the source tree to the state in which it was
1615     distributed, use <command>gmake distclean</>. If you are going to
1616     build for several platforms within the same source tree you must do
1617     this and re-configure for each build.  (Alternatively, use
1618     a separate build tree for each platform, so that the source tree
1619     remains unmodified.)
1620    </para>
1621   </formalpara>
1622
1623   <para>
1624    If you perform a build and then discover that your <command>configure</>
1625    options were wrong, or if you change anything that <command>configure</>
1626    investigates (for example, software upgrades), then it's a good
1627    idea to do <command>gmake distclean</> before reconfiguring and
1628    rebuilding.  Without this, your changes in configuration choices
1629    might not propagate everywhere they need to.
1630   </para>
1631  </sect1>
1632
1633  <sect1 id="install-post">
1634   <title>Post-Installation Setup</title>
1635
1636   <sect2>
1637    <title>Shared Libraries</title>
1638
1639    <indexterm>
1640     <primary>shared library</primary>
1641    </indexterm>
1642
1643    <para>
1644     On some systems that have shared libraries (which most systems do)
1645     you need to tell your system how to find the newly installed
1646     shared libraries.  The systems on which this is
1647     <emphasis>not</emphasis> necessary include <systemitem
1648     class="osname">BSD/OS</>, <systemitem class="osname">FreeBSD</>,
1649     <systemitem class="osname">HP-UX</>, <systemitem
1650     class="osname">IRIX</>, <systemitem class="osname">Linux</>,
1651     <systemitem class="osname">NetBSD</>, <systemitem
1652     class="osname">OpenBSD</>, <systemitem class="osname">Tru64
1653     UNIX</> (formerly <systemitem class="osname">Digital UNIX</>), and
1654     <systemitem class="osname">Solaris</>.
1655    </para>
1656
1657    <para>
1658     The method to set the shared library search path varies between
1659     platforms, but the most widely usable method is to set the
1660     environment variable <envar>LD_LIBRARY_PATH</> like so: In Bourne
1661     shells (<command>sh</>, <command>ksh</>, <command>bash</>, <command>zsh</>):
1662 <programlisting>
1663 LD_LIBRARY_PATH=/usr/local/pgsql/lib
1664 export LD_LIBRARY_PATH
1665 </programlisting>
1666     or in <command>csh</> or <command>tcsh</>:
1667 <programlisting>
1668 setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
1669 </programlisting>
1670     Replace <literal>/usr/local/pgsql/lib</> with whatever you set
1671     <option><literal>--libdir</></> to in <xref linkend="configure">.
1672     You should put these commands into a shell start-up file such as
1673     <filename>/etc/profile</> or <filename>~/.bash_profile</>.  Some
1674     good information about the caveats associated with this method can
1675     be found at <ulink
1676     url="http://www.visi.com/~barr/ldpath.html"></ulink>.
1677    </para>
1678
1679    <para>
1680     On some systems it might be preferable to set the environment
1681     variable <envar>LD_RUN_PATH</envar> <emphasis>before</emphasis>
1682     building.
1683    </para>
1684
1685    <para>
1686     On <systemitem class="osname">Cygwin</systemitem>, put the library
1687     directory in the <envar>PATH</envar> or move the
1688     <filename>.dll</filename> files into the <filename>bin</filename>
1689     directory.
1690    </para>
1691
1692    <para>
1693     If in doubt, refer to the manual pages of your system (perhaps
1694     <command>ld.so</command> or <command>rld</command>). If you later
1695     on get a message like
1696 <screen>
1697 psql: error in loading shared libraries
1698 libpq.so.2.1: cannot open shared object file: No such file or directory
1699 </screen>
1700     then this step was necessary.  Simply take care of it then.
1701    </para>
1702
1703    <para>
1704     <indexterm>
1705      <primary>ldconfig</primary>
1706     </indexterm>
1707     If you are on <systemitem class="osname">BSD/OS</>, <systemitem
1708     class="osname">Linux</>, or <systemitem class="osname">SunOS 4</>
1709     and you have root access you can run:
1710 <programlisting>
1711 /sbin/ldconfig /usr/local/pgsql/lib
1712 </programlisting>
1713     (or equivalent directory) after installation to enable the
1714     run-time linker to find the shared libraries faster.  Refer to the
1715     manual page of <command>ldconfig</> for more information.  On
1716     <systemitem class="osname">FreeBSD</>, <systemitem
1717     class="osname">NetBSD</>, and <systemitem
1718     class="osname">OpenBSD</> the command is:
1719 <programlisting>
1720 /sbin/ldconfig -m /usr/local/pgsql/lib
1721 </programlisting>
1722     instead.  Other systems are not known to have an equivalent
1723     command.
1724    </para>
1725   </sect2>
1726
1727   <sect2>
1728    <title>Environment Variables</title>
1729
1730    <indexterm>
1731     <primary><envar>PATH</envar></primary>
1732    </indexterm>
1733
1734    <para>
1735     If you installed into <filename>/usr/local/pgsql</> or some other
1736     location that is not searched for programs by default, you should
1737     add <filename>/usr/local/pgsql/bin</> (or whatever you set
1738     <option><literal>--bindir</></> to in <xref linkend="configure">)
1739     into your <envar>PATH</>.  Strictly speaking, this is not
1740     necessary, but it will make the use of <productname>PostgreSQL</>
1741     much more convenient.
1742    </para>
1743
1744    <para>
1745     To do this, add the following to your shell start-up file, such as
1746     <filename>~/.bash_profile</> (or <filename>/etc/profile</>, if you
1747     want it to affect every user):
1748 <programlisting>
1749 PATH=/usr/local/pgsql/bin:$PATH
1750 export PATH
1751 </programlisting>
1752     If you are using <command>csh</> or <command>tcsh</>, then use this command:
1753 <programlisting>
1754 set path = ( /usr/local/pgsql/bin $path )
1755 </programlisting>
1756    </para>
1757
1758    <para>
1759     <indexterm>
1760      <primary><envar>MANPATH</envar></primary>
1761     </indexterm>
1762     To enable your system to find the <application>man</>
1763     documentation, you need to add lines like the following to a
1764     shell start-up file unless you installed into a location that is
1765     searched by default:
1766 <programlisting>
1767 MANPATH=/usr/local/pgsql/man:$MANPATH
1768 export MANPATH
1769 </programlisting>
1770    </para>
1771
1772    <para>
1773     The environment variables <envar>PGHOST</> and <envar>PGPORT</>
1774     specify to client applications the host and port of the database
1775     server, overriding the compiled-in defaults. If you are going to
1776     run client applications remotely then it is convenient if every
1777     user that plans to use the database sets <envar>PGHOST</>.  This
1778     is not required, however: the settings can be communicated via command
1779     line options to most client programs.
1780    </para>
1781   </sect2>
1782  </sect1>
1783
1784
1785 <![%standalone-include;[
1786  <sect1 id="install-getting-started">
1787   <title>Getting Started</title>
1788
1789   <para>
1790    The following is a quick summary of how to get <productname>PostgreSQL</> up and
1791    running once installed. The main documentation contains more information.
1792   </para>
1793
1794   <procedure>
1795    <step>
1796     <para>
1797      Create a user account for the <productname>PostgreSQL</>
1798      server. This is the user the server will run as. For production
1799      use you should create a separate, unprivileged account
1800      (<quote>postgres</> is commonly used). If you do not have root
1801      access or just want to play around, your own user account is
1802      enough, but running the server as root is a security risk and
1803      will not work.
1804 <screen>
1805 <userinput>adduser postgres</>
1806 </screen>
1807     </para>
1808    </step>
1809
1810    <step>
1811     <para>
1812      Create a database installation with the <command>initdb</>
1813      command. To run <command>initdb</> you must be logged in to your
1814      <productname>PostgreSQL</> server account. It will not work as
1815      root.
1816 <screen>
1817 root# <userinput>mkdir /usr/local/pgsql/data</>
1818 root# <userinput>chown postgres /usr/local/pgsql/data</>
1819 root# <userinput>su - postgres</>
1820 postgres$ <userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</>
1821 </screen>
1822     </para>
1823
1824     <para>
1825      The <option>-D</> option specifies the location where the data
1826      will be stored. You can use any path you want, it does not have
1827      to be under the installation directory. Just make sure that the
1828      server account can write to the directory (or create it, if it
1829      doesn't already exist) before starting <command>initdb</>, as
1830      illustrated here.
1831     </para>
1832    </step>
1833
1834    <step>
1835     <para>
1836      At this point, if you did not use the <command>initdb</> <literal>-A</>
1837      option, you might want to modify <filename>pg_hba.conf</> to control
1838      local access to the server before you start it.  The default is to
1839      trust all local users.
1840     </para>
1841    </step>
1842
1843    <step>
1844     <para>
1845      The previous <command>initdb</> step should have told you how to
1846      start up the database server. Do so now. The command should look
1847      something like:
1848 <programlisting>
1849 /usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data
1850 </programlisting>
1851      This will start the server in the foreground. To put the server
1852      in the background use something like:
1853 <programlisting>
1854 nohup /usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data \
1855     &lt;/dev/null &gt;&gt;server.log 2&gt;&amp;1 &lt;/dev/null &amp;
1856 </programlisting>
1857     </para>
1858
1859     <para>
1860      To stop a server running in the background you can type:
1861 <programlisting>
1862 kill `cat /usr/local/pgsql/data/postmaster.pid`
1863 </programlisting>
1864     </para>
1865    </step>
1866
1867    <step>
1868     <para>
1869      Create a database:
1870 <screen>
1871 <userinput>createdb testdb</>
1872 </screen>
1873      Then enter
1874 <screen>
1875 <userinput>psql testdb</>
1876 </screen>
1877      to connect to that database. At the prompt you can enter SQL
1878      commands and start experimenting.
1879     </para>
1880    </step>
1881   </procedure>
1882  </sect1>
1883
1884  <sect1 id="install-whatnow">
1885   <title>What Now?</title>
1886
1887   <para>
1888    <itemizedlist>
1889     <listitem>
1890      <para>
1891       The <productname>PostgreSQL</> distribution contains a
1892       comprehensive documentation set, which you should read sometime.
1893       After installation, the documentation can be accessed by
1894       pointing your browser to
1895       <filename>/usr/local/pgsql/doc/html/index.html</>, unless you
1896       changed the installation directories.
1897      </para>
1898
1899      <para>
1900       The first few chapters of the main documentation are the Tutorial,
1901       which should be your first reading if you are completely new to
1902       <acronym>SQL</> databases.  If you are familiar with database
1903       concepts then you want to proceed with part on server
1904       administration, which contains information about how to set up
1905       the database server, database users, and authentication.
1906      </para>
1907     </listitem>
1908
1909     <listitem>
1910      <para>
1911       Usually, you will want to modify your computer so that it will
1912       automatically start the database server whenever it boots. Some
1913       suggestions for this are in the documentation.
1914      </para>
1915     </listitem>
1916
1917     <listitem>
1918      <para>
1919       Run the regression tests against the installed server (using
1920       <command>gmake installcheck</command>). If you didn't run the
1921       tests before installation, you should definitely do it now. This
1922       is also explained in the documentation.
1923      </para>
1924     </listitem>
1925
1926     <listitem>
1927      <para>
1928       By default, <productname>PostgreSQL</> is configured to run on
1929       minimal hardware.  This allows it to start up with almost any
1930       hardware configuration. The default configuration is, however,
1931       not designed for optimum performance. To achieve optimum
1932       performance, several server parameters must be adjusted, the two
1933       most common being <varname>shared_buffers</varname> and
1934       <varname>work_mem</varname>.
1935       Other parameters mentioned in the documentation also affect
1936       performance.
1937      </para>
1938     </listitem>
1939    </itemizedlist>
1940   </para>
1941  </sect1>
1942 ]]>
1943
1944
1945  <sect1 id="supported-platforms">
1946   <title>Supported Platforms</title>
1947
1948   <para>
1949    A platform (that is, a CPU architecture and operating system combination)
1950    is considered supported by the <productname>PostgreSQL</> development
1951    community if the code contains provisions to work on that platform and
1952    it has recently been verified to build and pass its regression tests
1953    on that platform.  Currently, most testing of platform compatibility
1954    is done automatically by test machines in the
1955    <ulink url="http://buildfarm.postgresql.org/">PostgreSQL Build Farm</ulink>.
1956    If you are interested in using <productname>PostgreSQL</> on a platform
1957    that is not represented in the build farm, but on which the code works
1958    or can be made to work, you are strongly encouraged to set up a build
1959    farm member machine so that continued compatibility can be assured.
1960   </para>
1961
1962   <para>
1963    In general, <productname>PostgreSQL</> can be expected to work on
1964    these CPU architectures: x86, x86_64, IA64, PowerPC,
1965    PowerPC 64, S/390, S/390x, Sparc, Sparc 64, Alpha, ARM, MIPS, MIPSEL, M68K,
1966    and PA-RISC.  Code support exists for M32R, NS32K, and VAX, but these
1967    architectures are not known to have been tested recently.  It is often
1968    possible to build on an unsupported CPU type by configuring with
1969    <option>--disable-spinlocks</option>, but performance will be poor.
1970   </para>
1971
1972   <para>
1973    <productname>PostgreSQL</> can be expected to work on these operating
1974    systems: Linux (all recent distributions), Windows (Win2000 SP4 and later),
1975    FreeBSD, OpenBSD, NetBSD, Mac OS X, AIX, HP/UX, IRIX, Solaris, Tru64 Unix,
1976    and UnixWare.  Other Unix-like systems may also work but are not currently
1977    being tested.  In most cases, all CPU architectures supported by
1978    a given operating system will work.  Look in the <filename>doc/</>
1979    directory of the source distribution to see if there is a FAQ document
1980    specific to your operating system, particularly if using an older system.
1981   </para>
1982
1983   <para>
1984    If you have installation problems on a platform that is known
1985    to be supported according to recent build farm results, please report
1986    it to <email>pgsql-bugs@postgresql.org</email>.  If you are interested
1987    in porting <productname>PostgreSQL</> to a new platform,
1988    <email>pgsql-ports@postgresql.org</email> is the appropriate place
1989    to discuss that.
1990   </para>
1991  </sect1>
1992
1993 </chapter>