Trim trailing whitespace

[postgresql] / doc / src / sgml / install-windows.sgml

<!-- doc/src/sgml/install-windows.sgml -->

<chapter id="install-windows">
 <title>Installation from Source Code on <productname>Windows</productname></title>

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

 <para>
  It is recommended that most users download the binary distribution for
  Windows, available as a graphical installer package
  from the <productname>PostgreSQL</productname> website. Building from source
  is only intended for people developing <productname>PostgreSQL</productname>
  or extensions.
 </para>

 <para>
  There are several different ways of building PostgreSQL on
  <productname>Windows</productname>. The simplest way to build with
  Microsoft tools is to install <productname>Visual Studio Express 2015
  for Windows Desktop</productname> and use the included
  compiler. It is also possible to build with the full
  <productname>Microsoft Visual C++ 2005 to 2015</productname>.
  In some cases that requires the installation of the
  <productname>Windows SDK</productname> in addition to the compiler.
 </para>

 <para>
  It is also possible to build PostgreSQL using the GNU compiler tools
  provided by <productname>MinGW</productname>, or using
  <productname>Cygwin</productname> for older versions of
  <productname>Windows</productname>.
 </para>

 <para>
  Building using <productname>MinGW</productname> or
  <productname>Cygwin</productname> uses the normal build system, see
  <xref linkend="installation"> and the specific notes in
  <xref linkend="installation-notes-mingw"> and <xref linkend="installation-notes-cygwin">.
  To produce native 64 bit binaries in these environments, use the tools from
  <productname>MinGW-w64</productname>. These tools can also be used to
  cross-compile for 32 bit and 64 bit <productname>Windows</productname>
  targets on other hosts, such as <productname>Linux</productname> and
  <productname>macOS</productname>.
  <productname>Cygwin</productname> is not recommended for running a
  production server, and it should only be used for running on
  older versions of <productname>Windows</productname> where
  the native build does not work, such as
  <productname>Windows 98</productname>. The official
  binaries are built using <productname>Visual Studio</productname>.
 </para>

 <para>
  Native builds of <application>psql</application> don't support command
  line editing. The <productname>Cygwin</productname> build does support
  command line editing, so it should be used where psql is needed for
  interactive use on  <productname>Windows</productname>.
 </para>

 <sect1 id="install-windows-full">
  <title>Building with <productname>Visual C++</productname> or the
  <productname>Microsoft Windows SDK</productname></title>

 <para>
  PostgreSQL can be built using the Visual C++ compiler suite from Microsoft.
  These compilers can be either from <productname>Visual Studio</productname>,
  <productname>Visual Studio Express</productname> or some versions of the
  <productname>Microsoft Windows SDK</productname>. If you do not already have a
  <productname>Visual Studio</productname> environment set up, the easiest
  ways are to use the compilers from <productname>Visual Studio Express 2015
  for Windows Desktop</productname> or those in the <productname>Windows SDK
  7.1</productname>, which are both free downloads from Microsoft.
 </para>

 <para>
  Both 32-bit and 64-bit builds are possible with the Microsoft Compiler suite.
  32-bit PostgreSQL builds are possible with
  <productname>Visual Studio 2005</productname> to
  <productname>Visual Studio 2015</productname> (including Express editions),
  as well as standalone Windows SDK releases 6.0 to 7.1.
  64-bit PostgreSQL builds are supported with
  <productname>Microsoft Windows SDK</productname> version 6.0a to 7.1 or
  <productname>Visual Studio 2008</productname> and above. Compilation
  is supported down to <productname>Windows XP</productname> and
  <productname>Windows Server 2003</> when building with
  <productname>Visual Studio 2005</> to
  <productname>Visual Studio 2013</productname>. Building with
  <productname>Visual Studio 2015</productname> is supported down to
  <productname>Windows Vista</> and <productname>Windows Server 2008</>.
 </para>

 <para>
  The tools for building using <productname>Visual C++</productname> or
  <productname>Platform SDK</productname> are in the
  <filename>src/tools/msvc</filename> directory. When building, make sure
  there are no tools from <productname>MinGW</productname> or
  <productname>Cygwin</productname> present in your system PATH. Also, make
  sure you have all the required Visual C++ tools available in the PATH. In
  <productname>Visual Studio</productname>, start the
  <application>Visual Studio Command Prompt</application>.
  If you wish to build a 64-bit version, you must use the 64-bit version of
  the command, and vice versa.
  In the <productname>Microsoft Windows SDK</productname>, start the
  <application>CMD shell</application> listed under the SDK on the Start Menu.
  In recent SDK versions you can change the targeted CPU architecture, build
  type, and target OS by using the <command>setenv</command> command, e.g.
  <command>setenv /x86 /release /xp</command> to target Windows XP or later
  with a 32-bit release build. See <command>/?</command> for other options to
  <command>setenv</command>.  All commands should be run from the
  <filename>src\tools\msvc</filename> directory.
 </para>

 <para>
  Before you build, you may need to edit the file <filename>config.pl</filename>
  to reflect any configuration options you want to change, or the paths to
  any third party libraries to use. The complete configuration is determined
  by first reading and parsing the file <filename>config_default.pl</filename>,
  and then apply any changes from <filename>config.pl</filename>. For example,
  to specify the location of your <productname>Python</productname> installation,
  put the following in <filename>config.pl</filename>:
<programlisting>
$config->{python} = 'c:\python26';
</programlisting>
  You only need to specify those parameters that are different from what's in
  <filename>config_default.pl</filename>.
 </para>

 <para>
  If you need to set any other environment variables, create a file called
  <filename>buildenv.pl</filename> and put the required commands there. For
  example, to add the path for bison when it's not in the PATH, create a file
  containing:
<programlisting>
$ENV{PATH}=$ENV{PATH} . ';c:\some\where\bison\bin';
</programlisting>
 </para>

 <para>
  To pass additional command line arguments to the Visual Studio build
  command (msbuild or vcbuild):
<programlisting>
$ENV{MSBFLAGS}="/m";
</programlisting>
 </para>

 <sect2>
  <title>Requirements</title>
  <para>
   The following additional products are required to build
   <productname>PostgreSQL</productname>. Use the
   <filename>config.pl</filename> file to specify which directories the libraries
   are available in.

   <variablelist>
    <varlistentry>
     <term><productname>Microsoft Windows SDK</productname></term>
     <listitem><para>
      If your build environment doesn't ship with a supported version of the
      <productname>Microsoft Windows SDK</productname> it
      is recommended that you upgrade to the latest version (currently
      version 7.1), available for download from
      <ulink url="https://www.microsoft.com/download"></>.
     </para>
     <para>
      You must always include the
      <application>Windows Headers and Libraries</application> part of the SDK.
      If you install a <productname>Windows SDK</productname>
      including the <application>Visual C++ Compilers</application>,
      you don't need <productname>Visual Studio</productname> to build.
      Note that as of Version 8.0a the Windows SDK no longer ships with a
      complete command-line build environment.
     </para></listitem>
    </varlistentry>

    <varlistentry>
     <term><productname>ActiveState Perl</productname></term>
     <listitem><para>
      ActiveState Perl is required to run the build generation scripts. MinGW
      or Cygwin Perl will not work. It must also be present in the PATH.
      Binaries can be downloaded from
      <ulink url="http://www.activestate.com"></> (Note: version 5.8 or later is required,
      the free Standard Distribution is sufficient).
     </para></listitem>
    </varlistentry>

   </variablelist>
  </para>
  <para>
   The following additional products are not required to get started,
   but are required to build the complete package. Use the
   <filename>config.pl</filename> file to specify which directories the libraries
   are available in.

   <variablelist>
    <varlistentry>
     <term><productname>ActiveState TCL</productname></term>
     <listitem><para>
      Required for building <application>PL/Tcl</application> (Note: version
      8.4 is required, the free Standard Distribution is sufficient).
     </para></listitem>
    </varlistentry>

    <varlistentry>
     <term><productname>Bison</productname> and
      <productname>Flex</productname></term>
     <listitem>
     <para>
      <productname>Bison</productname> and <productname>Flex</productname> are
      required to build from Git, but not required when building from a release
      file. Only <productname>Bison</productname> 1.875 or versions 2.2 and later
      will work. <productname>Flex</productname> must be version 2.5.31 or later.
     </para>

     <para>
      Both <productname>Bison</productname> and <productname>Flex</productname>
      are included in the <productname>msys</productname> tool suite, available
      from <ulink url="http://www.mingw.org/wiki/MSYS"></> as part of the
      <productname>MinGW</productname> compiler suite.
     </para>

     <para>
      You will need to add the directory containing
      <filename>flex.exe</filename> and <filename>bison.exe</filename> to the
      PATH environment variable in <filename>buildenv.pl</filename> unless
      they are already in PATH. In the case of MinGW, the directory is the
      <filename>\msys\1.0\bin</filename> subdirectory of your MinGW
      installation directory.
     </para>

     <note>
      <para>
        The Bison distribution from GnuWin32 appears to have a bug that
        causes Bison to malfunction when installed in a directory with
        spaces in the name, such as the default location on English
        installations <filename>C:\Program Files\GnuWin32</filename>.
        Consider installing into <filename>C:\GnuWin32</filename> or use the
        NTFS short name path to GnuWin32 in your PATH environment setting
        (e.g. <filename>C:\PROGRA~1\GnuWin32</filename>).
       </para>
     </note>

     <note>
       <para>
       The obsolete <literal>winflex</literal> binaries distributed on the PostgreSQL FTP site
       and referenced in older documentation will fail with <quote>flex: fatal
       internal error, exec failed</quote> on 64-bit Windows hosts. Use Flex from
       MSYS instead.
       </para>
     </note>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><productname>Diff</productname></term>
     <listitem><para>
      Diff is required to run the regression tests, and can be downloaded
      from <ulink url="http://gnuwin32.sourceforge.net"></>.
     </para></listitem>
    </varlistentry>

    <varlistentry>
     <term><productname>Gettext</productname></term>
     <listitem><para>
      Gettext is required to build with NLS support, and can be downloaded
      from <ulink url="http://gnuwin32.sourceforge.net"></>. Note that binaries,
      dependencies and developer files are all needed.
     </para></listitem>
    </varlistentry>

    <varlistentry>
     <term><productname>MIT Kerberos</productname></term>
     <listitem><para>
      Required for GSSAPI authentication support. MIT Kerberos can be
      downloaded from
      <ulink url="http://web.mit.edu/Kerberos/dist/index.html"></>.
     </para></listitem>
    </varlistentry>

    <varlistentry>
     <term><productname>libxml2</productname> and
      <productname>libxslt</productname></term>
     <listitem><para>
      Required for XML support. Binaries can be downloaded from
      <ulink url="http://zlatkovic.com/pub/libxml"></> or source from
      <ulink url="http://xmlsoft.org"></>. Note that libxml2 requires iconv,
      which is available from the same download location.
     </para></listitem>
    </varlistentry>

    <varlistentry>
     <term><productname>openssl</productname></term>
     <listitem><para>
      Required for SSL support. Binaries can be downloaded from
      <ulink url="http://www.slproweb.com/products/Win32OpenSSL.html"></>
      or source from <ulink url="http://www.openssl.org"></>.
     </para></listitem>
    </varlistentry>

    <varlistentry>
     <term><productname>ossp-uuid</productname></term>
     <listitem><para>
      Required for UUID-OSSP support (contrib only). Source can be
      downloaded from
      <ulink url="http://www.ossp.org/pkg/lib/uuid/"></>.
     </para></listitem>
    </varlistentry>

    <varlistentry>
     <term><productname>Python</productname></term>
     <listitem><para>
      Required for building <application>PL/Python</application>. Binaries can
      be downloaded from <ulink url="http://www.python.org"></>.
     </para></listitem>
    </varlistentry>

    <varlistentry>
     <term><productname>zlib</productname></term>
     <listitem><para>
      Required for compression support in <application>pg_dump</application>
      and <application>pg_restore</application>. Binaries can be downloaded
      from <ulink url="http://www.zlib.net"></>.
     </para></listitem>
    </varlistentry>

   </variablelist>
  </para>
 </sect2>

 <sect2>
  <title>Special Considerations for 64-bit Windows</title>

  <para>
   PostgreSQL will only build for the x64 architecture on 64-bit Windows, there
   is no support for Itanium processors.
  </para>

  <para>
   Mixing 32- and 64-bit versions in the same build tree is not supported.
   The build system will automatically detect if it's running in a 32- or
   64-bit environment, and build PostgreSQL accordingly. For this reason, it
   is important to start the correct command prompt before building.
  </para>

  <para>
   To use a server-side third party library such as <productname>python</> or
   <productname>openssl</>, this library <emphasis>must</emphasis> also be
   64-bit. There is no support for loading a 32-bit library in a 64-bit
   server. Several of the third party libraries that PostgreSQL supports may
   only be available in 32-bit versions, in which case they cannot be used with
   64-bit PostgreSQL.
  </para>
 </sect2>

 <sect2>
  <title>Building</title>

  <para>
   To build all of PostgreSQL in release configuration (the default), run the
   command:
<screen>
<userinput>build</userinput>
</screen>
   To build all of PostgreSQL in debug configuration, run the command:
<screen>
<userinput>build DEBUG</userinput>
</screen>
   To build just a single project, for example psql, run the commands:
<screen>
<userinput>build psql</userinput>
<userinput>build DEBUG psql</userinput>
</screen>
   To change the default build configuration to debug, put the following
   in the <filename>buildenv.pl</filename> file:
<programlisting>
$ENV{CONFIG}="Debug";
</programlisting>
  </para>

  <para>
   It is also possible to build from inside the Visual Studio GUI. In this
   case, you need to run:
<screen>
<userinput>perl mkvcbuild.pl</userinput>
</screen>
   from the command prompt, and then open the generated
   <filename>pgsql.sln</filename> (in the root directory of the source tree)
   in Visual Studio.
  </para>
 </sect2>

 <sect2>
  <title>Cleaning and Installing</title>

  <para>
   Most of the time, the automatic dependency tracking in Visual Studio will
   handle changed files. But if there have been large changes, you may need
   to clean the installation. To do this, simply run the
   <filename>clean.bat</filename> command, which will automatically clean out
   all generated files. You can also run it with the
   <parameter>dist</parameter> parameter, in which case it will behave like
   <userinput>make distclean</userinput> and remove the flex/bison output files
   as well.
  </para>

  <para>
   By default, all files are written into a subdirectory of the
   <filename>debug</filename> or <filename>release</filename> directories. To
   install these files using the standard layout, and also generate the files
   required to initialize and use the database, run the command:
<screen>
<userinput>install c:\destination\directory</userinput>
</screen>
  </para>

  <para>
   If you want to install only the client applications and
   interface libraries, then you can use these commands:
<screen>
<userinput>install c:\destination\directory client</userinput>
</screen>
  </para>
 </sect2>

 <sect2>
  <title>Running the Regression Tests</title>

  <para>
   To run the regression tests, make sure you have completed the build of all
   required parts first. Also, make sure that the DLLs required to load all
   parts of the system (such as the Perl and Python DLLs for the procedural
   languages) are present in the system path. If they are not, set it through
   the <filename>buildenv.pl</filename> file. To run the tests, run one of
   the following commands from the <filename>src\tools\msvc</filename>
   directory:
<screen>
<userinput>vcregress check</userinput>
<userinput>vcregress installcheck</userinput>
<userinput>vcregress plcheck</userinput>
<userinput>vcregress contribcheck</userinput>
<userinput>vcregress modulescheck</userinput>
<userinput>vcregress ecpgcheck</userinput>
<userinput>vcregress isolationcheck</userinput>
<userinput>vcregress bincheck</userinput>
<userinput>vcregress recoverycheck</userinput>
<userinput>vcregress upgradecheck</userinput>
</screen>

   To change the schedule used (default is parallel), append it to the
   command line like:
<screen>
<userinput>vcregress check serial</userinput>
</screen>

   For more information about the regression tests, see
   <xref linkend="regress">.
  </para>

  <para>
   Running the regression tests on client programs, with
   <command>vcregress bincheck</>, or on recovery tests, with
   <command>vcregress recoverycheck</>, requires an additional Perl module
   to be installed:
   <variablelist>
    <varlistentry>
     <term><productname>IPC::Run</productname></term>
     <listitem><para>
      As of this writing, <literal>IPC::Run</> is not included in the
      ActiveState Perl installation, nor in the ActiveState Perl Package
      Manager (PPM) library. To install, download the
      <filename>IPC-Run-&lt;version&gt;.tar.gz</> source archive from CPAN,
      at <ulink url="http://search.cpan.org/dist/IPC-Run/"></>, and
      uncompress. Edit the <filename>buildenv.pl</> file, and add a PERL5LIB
      variable to point to the <filename>lib</> subdirectory from the
      extracted archive. For example:
<programlisting>
$ENV{PERL5LIB}=$ENV{PERL5LIB} . ';c:\IPC-Run-0.94\lib';
</programlisting>
     </para></listitem>
    </varlistentry>
   </variablelist>
  </para>
 </sect2>

 <sect2>
  <title>Building the Documentation</title>

  <para>
   Building the PostgreSQL documentation in HTML format requires several tools
   and files. Create a root directory for all these files, and store them
   in the subdirectories in the list below.
   <variablelist>
    <varlistentry>
     <term>OpenJade 1.3.1-2</term>
     <listitem><para>
      Download from
      <ulink url="http://sourceforge.net/projects/openjade/files/openjade/1.3.1/openjade-1_3_1-2-bin.zip/download"></>
      and uncompress in the subdirectory <filename>openjade-1.3.1</filename>.
     </para></listitem>
    </varlistentry>

    <varlistentry>
     <term>DocBook DTD 4.2</term>
     <listitem><para>
      Download from
      <ulink url="http://www.oasis-open.org/docbook/sgml/4.2/docbook-4.2.zip"></>
      and uncompress in the subdirectory <filename>docbook</filename>.
     </para></listitem>
    </varlistentry>

    <varlistentry>
     <term>ISO character entities</term>
     <listitem><para>
      Download from
      <ulink url="http://www.oasis-open.org/cover/ISOEnts.zip"></> and
      uncompress in the subdirectory <filename>docbook</filename>.
     </para></listitem>
    </varlistentry>
   </variablelist>
   Edit the <filename>buildenv.pl</filename> file, and add a variable for the
   location of the root directory, for example:
<programlisting>
$ENV{DOCROOT}='c:\docbook';
</programlisting>
   To build the documentation, run the command
   <filename>builddoc.bat</filename>. Note that this will actually run the
   build twice, in order to generate the indexes. The generated HTML files
   will be in <filename>doc\src\sgml</filename>.
  </para>
 </sect2>

 </sect1>
</chapter>