installation.sgml

PostgreSQL7.4.6 for Linux

<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.177.2.8 2004/01/04 16:44:22 petere Exp $ -->

<chapter id="installation">
 <title><![%standalone-include[<productname>PostgreSQL</>]]>
  Installation Instructions</title>

 <indexterm zone="installation">
  <primary>installation</primary>
 </indexterm>

 <para>
  This <![%standalone-include;[document]]>
  <![%standalone-ignore;[chapter]]> describes the installation of
  <productname>PostgreSQL</productname> from the source code
  distribution.
 </para>

 <sect1 id="install-short">
  <title>Short Version</title>

  <para>
<synopsis>
./configure
gmake
su
gmake install
adduser postgres
mkdir /usr/local/pgsql/data
chown postgres /usr/local/pgsql/data
su - postgres
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data &gt;logfile 2&gt;&amp;1 &amp;
/usr/local/pgsql/bin/createdb test
/usr/local/pgsql/bin/psql test
</synopsis>
   The long version is the rest of this
   <![%standalone-include;[document.]]>
   <![%standalone-ignore;[chapter.]]>
  </para>
 </sect1>


 <sect1 id="install-requirements">
  <title>Requirements</title>

  <para>
   In general, a modern Unix-compatible platform should be able to run
   <productname>PostgreSQL</>.
    The platforms that had received specific testing at the
   time of release are listed in <xref linkend="supported-platforms">
   below. In the <filename>doc</> subdirectory of the distribution
   there are several platform-specific <acronym>FAQ</> documents you
   might wish to consult if you are having trouble.
  </para>

  <para>
   The following software packages are required for building
   <productname>PostgreSQL</>:

   <itemizedlist>
    <listitem>
     <para>
      <indexterm>
       <primary>make</primary>
      </indexterm>

      <acronym>GNU</> <application>make</> is required; other
      <application>make</> programs will <emphasis>not</> work.
      <acronym>GNU</> <application>make</> is often installed under
      the name <filename>gmake</filename>; this document will always
      refer to it by that name. (On some systems
      <acronym>GNU</acronym> <application>make</> is the default tool with the name
      <filename>make</>.) To test for <acronym>GNU</acronym>
      <application>make</application> enter
<screen>
<userinput>gmake --version</userinput>
</screen>
      It is recommended to use version 3.76.1 or later.
     </para>
    </listitem>

    <listitem>
     <para>
      You need an <acronym>ISO</>/<acronym>ANSI</> C compiler. Recent
      versions of <productname>GCC</> are recommendable, but
      <productname>PostgreSQL</> is known to build with a wide variety
      of compilers from different vendors.
     </para>
    </listitem>

    <listitem>
     <para>
      <application>gzip</> is needed to unpack the distribution in the
      first place.<![%standalone-include;[  If you are reading this, you probably already got
      past that hurdle.]]>
     </para>
    </listitem>

    <listitem>
     <para>
      <indexterm>
       <primary>readline</primary>
      </indexterm>

      The <acronym>GNU</> <productname>Readline</> library (for
      comfortable line editing and command history retrieval) will be
      used by default.  If you don't want to use it then you must
      specify the <option>--without-readline</option> option for
      <filename>configure</>.  (On <productname>NetBSD</productname>,
      the <filename>libedit</filename> library is
      <productname>Readline</productname>-compatible and is used if
      <filename>libreadline</filename> is not found.)
     </para>
    </listitem>

    <listitem>
     <para>
      <indexterm>
       <primary>installation</primary>
       <secondary>on Windows</secondary>
      </indexterm>

      To build on <productname>Windows NT</> or <productname>Windows
      2000</> you need the <productname>Cygwin</> and
      <productname>cygipc</> packages. See the file
      <filename>doc/FAQ_MSWIN</> for details.
     </para>
    </listitem>
   </itemizedlist>
  </para>

  <para>
   The following packages are optional.  They are not required in the
   default configuration, but they are needed when certain build
   options are enabled, as explained below.

   <itemizedlist>
    <listitem>
     <para>
      To build the server programming language PL/Perl you need a full
      <productname>Perl</productname> installation, including the
      <filename>libperl</filename> library and the header files.
      Since PL/Perl will be a shared library, the
      <indexterm><primary>libperl</primary></indexterm>
      <filename>libperl</filename> library must be a shared library
      also on most platforms.  This appears to be the default in
      recent Perl versions, but it was not in earlier versions, and in
      general it is the choice of whomever installed Perl at your
      site.
     </para>

     <para>
      If you don't have the shared library but you need one, a message
      like this will appear during the build to point out this fact:
<screen>
*** Cannot build PL/Perl because libperl is not a shared library.
*** You might have to rebuild your Perl installation.  Refer to
*** the documentation for details.
</screen>
      (If you don't follow the on-screen output you will merely notice
      that the PL/Perl library object, <filename>plperl.so</filename>
      or similar, will not be installed.)  If you see this, you will
      have to rebuild and install <productname>Perl</productname>
      manually to be able to build PL/Perl.  During the configuration
      process for <productname>Perl</productname>, request a shared
      library.
     </para>
    </listitem>

    <listitem>
     <para>
      To build the PL/Python server programming language, you need a
      Python installation, including the header files.  Since
      PL/Python will be a shared library, the
      <indexterm><primary>libpython</primary></indexterm>
      <filename>libpython</filename> library must be a shared library
      also on most platforms.  This is not the case in a default
      Python installation.
     </para>

     <para>
      If after building and installing you have a file called
      <filename>plpython.so</filename> (possibly a different
      extension), then everything went well.  Otherwise you should
      have seen a notice like this flying by:
<screen>
*** Cannot build PL/Python because libpython is not a shared library.
*** You might have to rebuild your Python installation.  Refer to
*** the documentation for details.
</screen>
      That means you have to rebuild (part of) your Python
      installation to supply this shared library.
     </para>

     <para>
      The catch is that the Python distribution or the Python
      maintainers do not provide any direct way to do this.  The
      closest thing we can offer you is the information in <ulink
      url="http://www.python.org/doc/FAQ.html#3.30">Python FAQ
      3.30</ulink>.  On some operating systems you don't really have
      to build a shared library, but then you will have to convince
      the <productname>PostgreSQL</> build system of this.  Consult
      the <filename>Makefile</filename> in the
      <filename>src/pl/plpython</filename> directory for details.
     </para>
    </listitem>

    <listitem>
     <para>
      If you want to build Tcl or Tk components (clients and the
      PL/Tcl language) you of course need a Tcl installation.
     </para>
    </listitem>

    <listitem>
     <para>
      To build the JDBC driver, you need
      <application>Ant</application> 1.5 or higher and a
      <acronym>JDK</acronym>.  <application>Ant</application> is a
      special tool for building Java-based packages.  It can be
      downloaded from the <ulink
      url="http://jakarta.apache.org/ant/index.html"><application>Ant</application>
      web site</ulink>.
     </para>

     <para>
      If you have several Java compilers installed, it depends on the
      Ant configuration which one gets used.  Precompiled
      <application>Ant</application> distributions are typically set
      up to read a file <filename>.antrc</filename> in the current
      user's home directory for configuration.  For example, to use a
      different <acronym>JDK</acronym> than the default, this may
      work:
<programlisting>
JAVA_HOME=/usr/local/sun-jdk1.3
JAVACMD=$JAVA_HOME/bin/java
</programlisting>
     </para>

     <note>
      <para>
       Do not try to build the driver by calling
       <command>ant</command> or even <command>javac</command>
       directly.  This will not work.  Run <command>gmake</command>
       normally as described below.
      </para>
     </note>
    </listitem>

    <listitem>
     <para>
      To enable Native Language Support (<acronym>NLS</acronym>), that
      is, the ability to display a program's messages in a language
      other than English, you need an implementation of the
      <application>Gettext</> <acronym>API</acronym>.  Some operating
      systems have this built-in (e.g., <systemitem
      class="osname">Linux</>, <systemitem class="osname">NetBSD</>,
      <systemitem class="osname">Solaris</>), for other systems you
      can download an add-on package from here: <ulink
      url="http://developer.postgresql.org/~petere/bsd-gettext/" ></ulink>.
      If you are using the <application>Gettext</> implementation in
      the <acronym>GNU</acronym> C library then you will additionally
      need the <productname>GNU Gettext</productname> package for some
      utility programs.  For any of the other implementations you will
      not need it.
     </para>
    </listitem>

    <listitem>
     <para>
      <application>Kerberos</>, <application>OpenSSL</>, or <application>PAM</>,
      if you want to support authentication using these services.
     </para>
    </listitem>
   </itemizedlist>
  </para>

  <para>
   If you are building from a <acronym>CVS</acronym> tree instead of
   using a released source package, or if you want to do development,
   you also need the following packages:

   <itemizedlist>
    <listitem>
     <para>
      <indexterm>
       <primary>flex</primary>
      </indexterm>
      <indexterm>
       <primary>bison</primary>
      </indexterm>
      <indexterm>
       <primary>yacc</primary>
      </indexterm>

      <application>Flex</> and <application>Bison</>
      are needed to build a CVS checkout or if you changed the actual
      scanner and parser definition files. If you need them, be sure
      to get <application>Flex</> 2.5.4 or later and
      <application>Bison</> 1.875 or later. Other <application>yacc</>
      programs can sometimes be used, but doing so requires extra
      effort and is not recommended. Other <application>lex</>
      programs will definitely not work.
     </para>
    </listitem>
   </itemizedlist>
  </para>

  <para>
   If you need to get a <acronym>GNU</acronym> package, you can find
   it at your local <acronym>GNU</acronym> mirror site (see <ulink
   url="http://www.gnu.org/order/ftp.html"></>
   for a list) or at <ulink
   url="ftp://ftp.gnu.org/gnu/"></ulink>.
  </para>

  <para>
   Also check that you have sufficient disk space. You will need about
   65 MB for the source tree during compilation and about 15 MB for
   the installation directory. An empty database cluster takes about
   25 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
   90 MB. Use the <command>df</command> command to check for disk
   space.
  </para>
 </sect1>

<![%standalone-ignore;[
 <sect1 id="install-getsource">
  <title>Getting The Source</title>

  <para>
   The <productname>PostgreSQL</> &version; sources can be obtained by
   anonymous FTP from <ulink
   url="ftp://ftp.postgresql.org/pub/source/v&version;/postgresql-&version;.tar.gz"></ulink>.
   Use a mirror if possible. After you have obtained the file, unpack it:
<screen>
<userinput>gunzip postgresql-&version;.tar.gz</userinput>
<userinput>tar xf postgresql-&version;.tar</userinput>
</screen>
   This will create a directory
   <filename>postgresql-&version;</filename> under the current directory
   with the <productname>PostgreSQL</> sources.
   Change into that directory for the rest
   of the installation procedure.
  </para>
 </sect1>
]]>

 <sect1 id="install-upgrading">
  <title>If You Are Upgrading</title>

  <indexterm zone="install-upgrading">
   <primary>upgrading</primary>
  </indexterm>

  <para>
   The internal data storage format changes with new releases of
   <productname>PostgreSQL</>. Therefore, if you are upgrading an
   existing installation that does not have a version number
   <quote>&majorversion;.x</quote>, you must back up and restore your
   data as shown here. These instructions assume that your existing
   installation is under the <filename>/usr/local/pgsql</> directory,
   and that the data area is in <filename>/usr/local/pgsql/data</>.
   Substitute your paths appropriately.
  </para>