doc/src/sgml/install-win32.sgml

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