doc/src/sgml/install-win32.sgml

   1 <!-- $PostgreSQL: pgsql/doc/src/sgml/install-win32.sgml,v 1.44 2007/12/19 12:29:36 mha Exp $ -->
   2
   3 <chapter id="install-win32">
   4  <title>Installation on <productname>Windows</productname></title>
   5
   6  <indexterm>
   7   <primary>installation</primary>
   8   <secondary>on Windows</secondary>
   9  </indexterm>
  10
  11  <para>
  12   It is recommended that most users download the binary distribution for
  13   Windows, available as a <productname>Windows Installer</productname> package
  14   from the <productname>PostgreSQL</productname> website. Building from source
  15   is only intended for people developing <productname>PostgreSQL</productname>
  16   or extensions.
  17  </para>
  18
  19  <para>
  20   There are several different ways of building PostgreSQL on
  21   <productname>Windows</productname>. The complete system can
  22   be built using <productname>MinGW</productname> or
  23   <productname>Visual C++ 2005</productname>. It can also be
  24   built for older versions of <productname>Windows</productname> using
  25   <productname>Cygwin</productname>. Finally, the client access library
  26   (<application>libpq</application>) can be built using
  27   <productname>Visual C++ 7.1</productname> or
  28   <productname>Borland C++</productname> for compatibility with statically
  29   linked applications built using these tools.
  30  </para>
  31
  32  <para>
  33   Building using <productname>MinGW</productname> or
  34   <productname>Cygwin</productname> uses the normal build system, see
  35   <xref linkend="installation"> and the FAQs in
  36   <filename>doc/FAQ_MINGW</filename> and <filename>do/FAQ_CYGWIN</filename>.
  37   Note that <productname>Cygwin</productname> is not recommended, and should
  38   only be used for older versions of <productname>Windows</productname> where
  39   the native build does not work, such as
  40   <productname>Windows 98</productname>.
  41  </para>
  42
  43  <sect1 id="install-win32-full">
  44   <title>Building with <productname>Visual C++ 2005</productname></title>
  45
  46  <para>
  47   The tools for building using <productname>Visual C++ 2005</productname>,
  48   are in the <filename>src/tools/msvc</filename> directory. When building,
  49   make sure there are no tools from <productname>MinGW</productname> or
  50   <productname>Cygwin</productname> present in your system PATH. Also, make
  51   sure you have all the required Visual C++ tools available in the PATH,
  52   usually by starting a <application>Visual Studio Command Prompt</application>
  53   and running the commands from there. All commands should be run from the
  54   <filename>src\tools\msvc</filename> directory.
  55  </para>
  56
  57  <para>
  58   Before you build, edit the file <filename>config.pl</filename> to reflect the
  59   configuration options you want set, including the paths to libraries used.
  60   If you need to set any other environment variables, create a file called
  61   <filename>buildenv.pl</filename> and put the required commands there. For
  62   example, to add the path for bison when it's not in the PATH, create a file
  63   containing:
  64   <screen>
  65    $ENV{PATH}=$ENV{PATH} . ';c:\some\where\bison\bin';
  66   </screen>
  67  </para>
  68
  69  <sect2>
  70   <title>Requirements</title>
  71   <para>
  72    PostgreSQL will build using either the professional versions (any edition)
  73    or the free Express edition of
  74    <productname>Visual Studio 2005</productname>. The following additional products
  75    are required to build the complete package. Use the
  76    <filename>config.pl</filename> to specify which directories the libraries
  77    are available in.
  78
  79    <variablelist>
  80     <varlistentry>
  81      <term><productname>ActiveState Perl</productname></term>
  82      <listitem><para>
  83       ActiveState Perl is required to run the build generation scripts. MinGW
  84       or Cygwin Perl will not work. It must also be present in the PATH.
  85       Binaries can be downloaded from
  86       <ulink url="http://www.activestate.com"></>.
  87      </para></listitem>
  88     </varlistentry>
  89
  90     <varlistentry>
  91      <term><productname>ActiveState TCL</productname></term>
  92      <listitem><para>
  93       Required for building <application>PL/TCL</application>.
  94      </para></listitem>
  95     </varlistentry>
  96
  97     <varlistentry>
  98      <term><productname>Bison</productname> and
  99       <productname>Flex</productname></term>
 100      <listitem><para>
 101       Bison and Flex are required to build from CVS, but not required when
 102       building from a release file. Note that only Bison 1.875 or versions
 103       2.2 and later will work. Bison and Flex can be
 104       downloaded from <ulink url="http://gnuwin32.sourceforge.net"></>.
 105      </para></listitem>
 106     </varlistentry>
 107
 108     <varlistentry>
 109      <term><productname>Diff</productname></term>
 110      <listitem><para>
 111       Diff is required to run the regression tests, and can be downloaded
 112       from <ulink url="http://gnuwin32.sourceforge.net"></>.
 113      </para></listitem>
 114     </varlistentry>
 115
 116     <varlistentry>
 117      <term><productname>Gettext</productname></term>
 118      <listitem><para>
 119       Gettext is required to build with NLS support, and can be downloaded
 120       from <ulink url="http://gnuwin32.sourceforge.net"></>. Note that binaries,
 121       dependencies and developer files are all needed.
 122      </para></listitem>
 123     </varlistentry>
 124
 125     <varlistentry>
 126      <term><productname>Microsoft Platform SDK</productname></term>
 127      <listitem><para>
 128       It is recommended that you upgrade to the latest available version
 129       of the <productname>Microsoft Platform SDK</productname>, available
 130       for download from <ulink url="http://www.microsoft.com/downloads/"></>.
 131      </para></listitem>
 132     </varlistentry>
 133
 134     <varlistentry>
 135      <term><productname>MIT Kerberos</productname></term>
 136      <listitem><para>
 137       Required for Kerberos authentication support. MIT Kerberos can be
 138       downloaded from
 139       <ulink url="http://web.mit.edu/Kerberos/dist/index.html"></>.
 140      </para></listitem>
 141     </varlistentry>
 142
 143     <varlistentry>
 144      <term><productname>libxml2</productname> and
 145       <productname>libxslt</productname></term>
 146      <listitem><para>
 147       Required for XML support. Binaries can be downloaded from
 148       <ulink url="http://zlatkovic.com/pub/libxml"></> or source from
 149       <ulink url="http://xmlsoft.org"></>. Note that libxml2 requires iconv,
 150       which is available from the same download location.
 151      </para></listitem>
 152     </varlistentry>
 153
 154     <varlistentry>
 155      <term><productname>openssl</productname></term>
 156      <listitem><para>
 157       Required for SSL support. Binaries can be downloaded from
 158       <ulink url="http://www.slproweb.com/products/Win32OpenSSL.html"></>
 159       or source from <ulink url="http://www.openssl.org"></>.
 160      </para></listitem>
 161     </varlistentry>
 162
 163     <varlistentry>
 164      <term><productname>Python</productname></term>
 165      <listitem><para>
 166       Required for building <application>PL/Python</application>. Binaries can
 167       be downloaded from <ulink url="http://www.python.org"></>.
 168      </para></listitem>
 169     </varlistentry>
 170
 171     <varlistentry>
 172      <term><productname>zlib</productname></term>
 173      <listitem><para>
 174       Required for compression support in <application>pg_dump</application>
 175       and <application>pg_restore</application>. Binaries can be downloaded
 176       from <ulink url="http://www.zlib.net"></>.
 177      </para></listitem>
 178     </varlistentry>
 179
 180    </variablelist>
 181   </para>
 182  </sect2>
 183
 184  <sect2>
 185   <title>Building</title>
 186
 187   <para>
 188    To build all of PostgreSQL in release configuration (the default), run the
 189    command:
 190    <screen>
 191     <userinput>
 192      build
 193     </userinput>
 194    </screen>
 195    To build all of PostgreSQL in debug configuration, run the command:
 196    <screen>
 197     <userinput>
 198      build DEBUG
 199     </userinput>
 200    </screen>
 201    To build just a single project, for example psql, run the commands:
 202    <screen>
 203     <userinput>
 204      build psql
 205     </userinput>
 206     <userinput>
 207      build DEBUG psql
 208     </userinput>
 209    </screen>
 210    To change the default build configuration to debug, put the following
 211    in the <filename>buildenv.pl</filename> file:
 212    <screen>
 213     <userinput>
 214      $ENV{CONFIG}="Debug";
 215     </userinput>
 216    </screen>
 217   </para>
 218
 219   <para>
 220    It is also possible to build from inside the Visual Studio GUI. In this
 221    case, you need to run:
 222    <screen>
 223     <userinput>
 224      perl mkvcbuild.pl
 225     </userinput>
 226    </screen>
 227    from the command prompt, and then open the generated
 228    <filename>pgsql.sln</filename> (in the root directory of the source tree)
 229    in Visual Studio.
 230   </para>
 231  </sect2>
 232
 233  <sect2>
 234   <title>Cleaning and installing</title>
 235
 236   <para>
 237    Most of the time, the automatic dependency tracking in Visual Studio will
 238    handle changed files. But if there have been large changes, you may need
 239    to clean the installation. To do this, simply run the
 240    <filename>clean.bat</filename> command, which will automatically clean out
 241    all generated files.
 242   </para>
 243
 244   <para>
 245    By default, all files are written into a subdirectory of the
 246    <filename>debug</filename> or <filename>release</filename> directories. To
 247    install these files using the standard layout, and also generate the files
 248    required to initialize and use the database, run the command:
 249    <screen>
 250     <userinput>
 251      perl install.pl c:\destination\directory
 252     </userinput>
 253    </screen>
 254   </para>
 255  </sect2>
 256
 257  <sect2>
 258   <title>Running the regression tests</title>
 259
 260   <para>
 261    To run the regression tests, make sure you have completed the build of all
 262    required parts first. Also, make sure that the DLLs required to load all
 263    parts of the system (such as the Perl and Python DLLs for the procedural
 264    languages) are present in the system path. If they are not, set it through
 265    the <filename>buildenv.pl</filename> file. To run the tests, run one of
 266    the following commands from the <filename>src\tools\msvc</filename>
 267    directory:
 268    <screen>
 269     <userinput>
 270      vcregress check
 271     </userinput>
 272     <userinput>
 273      vcregress installcheck
 274     </userinput>
 275     <userinput>
 276      vcregress plcheck
 277     </userinput>
 278     <userinput>
 279      vcregress contribcheck
 280     </userinput>
 281    </screen>
 282
 283    To change the schedule used (default is the parallel), append it to the
 284    command line like:
 285    <screen>
 286     <userinput>
 287      vcregress check serial
 288     </userinput>
 289    </screen>
 290
 291    For more information about the regression tests, see
 292    <xref linkend="regress">.
 293   </para>
 294  </sect2>
 295
 296  <sect2>
 297   <title>Building the documentation</title>
 298
 299   <para>
 300    Building the PostgreSQL documentation in HTML format requires several tools
 301    and files. Create a root directory for all these files, and store them
 302    in the subdirectories in the list below.
 303    <variablelist>
 304     <varlistentry>
 305      <term>OpenJade 1.3.1-2</term>
 306      <listitem><para>
 307       Download from
 308       <ulink url="http://sourceforge.net/project/downloading.php?groupname=openjade&amp;filename=openjade-1_3_1-2-bin.zip"></>
 309       and uncompress in the subdirectory <filename>openjade-1.3.1</filename>.
 310      </para></listitem>
 311     </varlistentry>
 312
 313     <varlistentry>
 314      <term>DocBook DTD 4.2</term>
 315      <listitem><para>
 316       Download from
 317       <ulink url="http://www.oasis-open.org/docbook/sgml/4.2/docbook-4.2.zip"></>
 318       and uncompress in the subdirectory <filename>docbook</filename>.
 319      </para></listitem>
 320     </varlistentry>
 321
 322     <varlistentry>
 323      <term>DocBook DSSSL 1.79</term>
 324      <listitem><para>
 325       Download from
 326       <ulink url="http://sourceforge.net/project/downloading.php?groupname=docbook&amp;filename=docbook-dsssl-1.79.zip"></>
 327       and uncompress in the subdirectory
 328       <filename>docbook-dsssl-1.79</filename>.
 329      </para></listitem>
 330     </varlistentry>
 331
 332     <varlistentry>
 333      <term>ISO character entities</term>
 334      <listitem><para>
 335       Download from
 336       <ulink url="http://www.oasis-open.org/cover/ISOEnts.zip"></> and
 337       uncompress in the subdirectory <filename>docbook</filename>.
 338      </para></listitem>
 339     </varlistentry>
 340    </variablelist>
 341    Edit the <filename>buildenv.pl</filename> file, and add a variable for the
 342    location of the root directory, for example:
 343    <screen>
 344     $ENV{DOCROOT}='c:\docbook';
 345    </screen>
 346    To build the documentation, run the command
 347    <filename>builddoc.bat</filename>. Note that this will actually run the
 348    build twice, in order to generate the indexes. The generated HTML files
 349    will be in <filename>doc\src\sgml</filename>.
 350   </para>
 351  </sect2>
 352
 353  </sect1>
 354
 355  <sect1 id="install-win32-libpq">
 356   <title>Building <application>libpq</application> with
 357   <productname>Visual C++</productname> or
 358   <productname>Borland C++</productname></title>
 359
 360  <para>
 361   Using <productname>Visual C++ 7.1-8.0</productname> or
 362   <productname>Borland C++</productname> to build libpq is only recommended
 363   if you need a version with different debug/release flags, or if you need a
 364   static library to link into an application. For normal use the
 365   <productname>MinGW</productname> or
 366   <productname>Visual Studio 2005</productname> version is recommended.
 367  </para>
 368
 369  <para>
 370   To build the <application>libpq</application> client library using
 371   <productname>Visual Studio 7.1 or later</productname>, change into the
 372   <filename>src</filename> directory and type the command
 373 <screen>
 374 <userinput>nmake /f win32.mak</userinput>
 375 </screen>
 376  </para>
 377  <para>
 378  To build a 64-bit version of the <application>libpq</application>
 379  client library using <productname>Visual Studio 8.0 or
 380  later</productname>, change into the <filename>src</filename>
 381  directory and type in the command
 382 <screen>
 383 <userinput>nmake /f win32.mak CPU=AMD64</userinput>
 384 </screen>
 385  See the <filename>win32.mak</filename> file for further details
 386  about supported variables.
 387  </para>
 388
 389  <para>
 390   To build the <application>libpq</application> client library using
 391   <productname>Borland C++</productname>, change into the
 392   <filename>src</filename> directory and type the command
 393 <screen>
 394 <userinput>make -N -DCFG=Release /f bcc32.mak</userinput>
 395 </screen>
 396  </para>
 397
 398  <sect2>
 399  <title>Generated files</title>
 400  <para>
 401   The following files will be built:
 402
 403   <variablelist>
 404    <varlistentry>
 405     <term><filename>interfaces\libpq\Release\libpq.dll</filename></term>
 406     <listitem>
 407      <para>
 408       The dynamically linkable frontend library
 409      </para>
 410     </listitem>
 411    </varlistentry>
 412
 413    <varlistentry>
 414     <term><filename>interfaces\libpq\Release\libpqdll.lib</filename></term>
 415     <listitem>
 416      <para>
 417       Import library to link your programs to <filename>libpq.dll</filename>
 418      </para>
 419     </listitem>
 420    </varlistentry>
 421
 422    <varlistentry>
 423     <term><filename>interfaces\libpq\Release\libpq.lib</filename></term>
 424     <listitem>
 425      <para>
 426       Static version of the frontend library
 427      </para>
 428     </listitem>
 429    </varlistentry>
 430
 431   </variablelist>
 432  </para>
 433
 434  <para>
 435   Normally you do not need to install any of the client files. You should
 436   place the <filename>libpq.dll</filename> file in the same directory
 437   as your applications executable file. Do not install
 438   <filename>libpq.dll</filename> into your Windows, System or System32
 439   directory unless absolutely necessary.
 440   If this file is installed using a setup program, it should
 441   be installed with version checking using the
 442   <symbol>VERSIONINFO</symbol> resource included in the file, to
 443   ensure that a newer version of the library is not overwritten.
 444  </para>
 445
 446  <para>
 447   If you are planning to do development using <application>libpq</application>
 448   on this machine, you will have to add the
 449   <filename>src\include</filename> and
 450   <filename>src\interfaces\libpq</filename> subdirectories of the source
 451   tree to the include path in your compiler's settings.
 452  </para>
 453
 454  <para>
 455   To use the library, you must add the
 456   <filename>libpqdll.lib</filename> file to your project.  (In Visual
 457   C++, just right-click on the project and choose to add it.)
 458  </para>
 459  </sect2>
 460  </sect1>
 461 </chapter>