install-win32.sgml 16 KB
Newer Older
1
<!-- $PostgreSQL: pgsql/doc/src/sgml/install-win32.sgml,v 1.51 2009/01/09 13:37:18 petere Exp $ -->
2

Peter Eisentraut's avatar
Peter Eisentraut committed
3
<chapter id="install-win32">
4
 <title>Installation from Source Code on <productname>Windows</productname></title>
5

6 7 8 9 10
 <indexterm>
  <primary>installation</primary>
  <secondary>on Windows</secondary>
 </indexterm>

Peter Eisentraut's avatar
Peter Eisentraut committed
11
 <para>
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
  It is recommended that most users download the binary distribution for 
  Windows, available as a <productname>Windows Installer</productname> 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 complete system can
  be built using <productname>MinGW</productname> or
  <productname>Visual C++ 2005</productname>. It can also be
  built for older versions of <productname>Windows</productname> using
  <productname>Cygwin</productname>. Finally, the client access library
  (<application>libpq</application>) can be built using
27
  <productname>Visual C++ 7.1</productname> or 
28 29 30 31 32 33 34
  <productname>Borland C++</productname> for compatibility with statically
  linked applications built using these tools.
 </para>

 <para>
  Building using <productname>MinGW</productname> or
  <productname>Cygwin</productname> uses the normal build system, see
35 36 37
  <xref linkend="installation"> and the specific notes in
  <xref linkend="installation-notes-mingw"> and <xref linkend="installation-notes-cygwin">.
  <productname>Cygwin</productname> is not recommended and should
38 39 40 41 42
  only be used for older versions of <productname>Windows</productname> where
  the native build does not work, such as 
  <productname>Windows 98</productname>.
 </para>

43
 <sect1 id="install-win32-full">
44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60
  <title>Building with <productname>Visual C++ 2005</productname></title>

 <para>
  The tools for building using <productname>Visual C++ 2005</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,
  usually by starting a <application>Visual Studio Command Prompt</application>
  and running the commands from there. All commands should be run from the
  <filename>src\tools\msvc</filename> directory.
 </para>

 <para>
  Before you build, edit the file <filename>config.pl</filename> to reflect the
  configuration options you want set, including the paths to libraries used.
  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 63 64
  example, to add the path for bison when it's not in the PATH, create a file
  containing:
  <screen>
65
   $ENV{PATH}=$ENV{PATH} . ';c:\some\where\bison\bin';
66
  </screen>
Peter Eisentraut's avatar
Peter Eisentraut committed
67
 </para>
68

69 70 71 72
 <sect2>
  <title>Requirements</title>
  <para>
   PostgreSQL will build using either the professional versions (any edition)
73 74 75
   or the free Express edition of
   <productname>Visual Studio 2005</productname>. The following additional products
   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 80 81 82

   <variablelist>
    <varlistentry>
     <term><productname>ActiveState Perl</productname></term>
     <listitem><para>
83
      ActiveState Perl is required to run the build generation scripts. MinGW
Peter Eisentraut's avatar
Peter Eisentraut committed
84
      or Cygwin Perl will not work. It must also be present in the PATH.
85
      Binaries can be downloaded from
86 87
      <ulink url="http://www.activestate.com"></> (Note: version 5.8 is required,
      the free Standard Distribution is sufficient).
88
     </para></listitem>
89 90 91
    </varlistentry>

    <varlistentry>
92
     <term><productname>ActiveState TCL</productname></term>
93
     <listitem><para>
94 95
      Required for building <application>PL/TCL</application> (Note: version
      8.4 is required, the free Standard Distribution is sufficient).
96
     </para></listitem>
97 98 99 100
    </varlistentry>

    <varlistentry>
     <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 105
      building from a release file. Note that only Bison 1.875 or versions
      2.2 and later will work. Bison and Flex can be
106 107
      downloaded from <ulink url="http://gnuwin32.sourceforge.net"></>.
     </para></listitem>
108 109
    </varlistentry>

110 111 112 113 114 115 116 117
    <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>

118 119 120 121 122 123 124 125 126
    <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>

127 128 129 130 131 132 133 134
    <varlistentry>
     <term><productname>Microsoft Platform SDK</productname></term>
     <listitem><para>
      It is recommended that you upgrade to the latest available version
      of the <productname>Microsoft Platform SDK</productname>, available
      for download from <ulink url="http://www.microsoft.com/downloads/"></>.
     </para></listitem>
    </varlistentry>
135 136 137 138

    <varlistentry>
     <term><productname>MIT Kerberos</productname></term>
     <listitem><para>
139 140 141 142
      Required for Kerberos authentication support. MIT Kerberos can be
      downloaded from 
      <ulink url="http://web.mit.edu/Kerberos/dist/index.html"></>.
     </para></listitem>
143 144 145 146
    </varlistentry>

    <varlistentry>
     <term><productname>libxml2</productname> and
147
      <productname>libxslt</productname></term>
148 149
     <listitem><para>
      Required for XML support. Binaries can be downloaded from
150 151 152 153
      <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>
154 155 156 157 158 159 160
    </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"></>
161 162
      or source from <ulink url="http://www.openssl.org"></>.
     </para></listitem>
163 164
    </varlistentry>

165 166 167 168 169 170 171 172 173
    <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>

174 175 176 177
    <varlistentry>
     <term><productname>Python</productname></term>
     <listitem><para>
      Required for building <application>PL/Python</application>. Binaries can
178 179
      be downloaded from <ulink url="http://www.python.org"></>.
     </para></listitem>
180 181
    </varlistentry>

182 183
    <varlistentry>
     <term><productname>zlib</productname></term>
184
     <listitem><para>
185 186 187 188
      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>
189 190 191 192 193 194 195 196 197 198
    </varlistentry>

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

 <sect2>
  <title>Building</title>

  <para>
199
   To build all of PostgreSQL in release configuration (the default), run the
200
   command:
201 202 203 204 205
   <screen>
    <userinput>
     build
    </userinput>
   </screen>
206
   To build all of PostgreSQL in debug configuration, run the command:
207 208
   <screen>
    <userinput>
209
     build DEBUG
210 211 212 213 214 215 216 217
    </userinput>
   </screen>
   To build just a single project, for example psql, run the commands:
   <screen>
    <userinput>
     build psql
    </userinput>
    <userinput>
218 219 220 221
     build DEBUG psql
    </userinput>
   </screen>
   To change the default build configuration to debug, put the following
222
   in the <filename>buildenv.pl</filename> file:
223 224
   <screen>
    <userinput>
225
     $ENV{CONFIG}="Debug";
226 227 228 229
    </userinput>
   </screen>
  </para>

Peter Eisentraut's avatar
Peter Eisentraut committed
230
  <para>
231
   It is also possible to build from inside the Visual Studio GUI. In this
232
   case, you need to run:
233 234 235 236 237 238
   <screen>
    <userinput>
     perl mkvcbuild.pl
    </userinput>
   </screen>
   from the command prompt, and then open the generated
239 240
   <filename>pgsql.sln</filename> (in the root directory of the source tree)
   in Visual Studio.
Peter Eisentraut's avatar
Peter Eisentraut committed
241
  </para>
242 243 244 245 246 247 248
 </sect2>

 <sect2>
  <title>Cleaning and installing</title>

  <para>
   Most of the time, the automatic dependency tracking in Visual Studio will
249 250 251
   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
252
   all generated files. You can also run it with the
253 254 255
   <parameter>dist</parameter> parameter, in which case it will behave like
   <userinput>make distclean</userinput> and remove the flex/bison output files
   as well.
256 257 258 259
  </para>

  <para>
   By default, all files are written into a subdirectory of the
260 261 262
   <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:
263 264 265 266 267 268 269 270
   <screen>
    <userinput>
     perl install.pl c:\destination\directory
    </userinput>
   </screen>
  </para>
 </sect2>

271 272 273 274 275 276
 <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
Peter Eisentraut's avatar
Peter Eisentraut committed
277 278
   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
279
   the <filename>buildenv.pl</filename> file. To run the tests, run one of
280 281 282 283 284 285 286 287 288 289 290 291
   the following commands from the <filename>src\tools\msvc</filename>
   directory:
   <screen>
    <userinput>
     vcregress check
    </userinput>
    <userinput>
     vcregress installcheck
    </userinput>
    <userinput>
     vcregress plcheck
    </userinput>
292 293 294
    <userinput>
     vcregress contribcheck
    </userinput>
295 296 297
   </screen>

   To change the schedule used (default is the parallel), append it to the
Peter Eisentraut's avatar
Peter Eisentraut committed
298
   command line like:
299 300 301 302 303 304 305 306 307 308 309
   <screen>
    <userinput>
     vcregress check serial
    </userinput>
   </screen>

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

310 311 312 313 314
 <sect2>
  <title>Building the documentation</title>

  <para>
   Building the PostgreSQL documentation in HTML format requires several tools
315 316
   and files. Create a root directory for all these files, and store them
   in the subdirectories in the list below.
317 318 319 320 321
   <variablelist>
    <varlistentry>
     <term>OpenJade 1.3.1-2</term>
     <listitem><para>
      Download from
322 323
      <ulink url="http://sourceforge.net/project/downloading.php?groupname=openjade&amp;filename=openjade-1_3_1-2-bin.zip"></>
      and uncompress in the subdirectory <filename>openjade-1.3.1</filename>.
324 325 326 327 328 329 330
     </para></listitem>
    </varlistentry>

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

    <varlistentry>
Peter Eisentraut's avatar
Peter Eisentraut committed
337
     <term>DocBook DSSSL 1.79</term>
338 339 340 341
     <listitem><para>
      Download from
      <ulink url="http://sourceforge.net/project/downloading.php?groupname=docbook&amp;filename=docbook-dsssl-1.79.zip"></>
      and uncompress in the subdirectory
342
      <filename>docbook-dsssl-1.79</filename>.
343 344 345 346 347 348 349
     </para></listitem>
    </varlistentry>

    <varlistentry>
     <term>ISO character entities</term>
     <listitem><para>
      Download from
350 351
      <ulink url="http://www.oasis-open.org/cover/ISOEnts.zip"></> and
      uncompress in the subdirectory <filename>docbook</filename>.
352 353 354
     </para></listitem>
    </varlistentry>
   </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 360
   </screen>
   To build the documentation, run the command
361 362 363
   <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>.
364 365 366 367 368
  </para>
 </sect2>

 </sect1>

369
 <sect1 id="install-win32-libpq">
370 371 372
  <title>Building <application>libpq</application> with
  <productname>Visual C++</productname> or
  <productname>Borland C++</productname></title>
373

Peter Eisentraut's avatar
Peter Eisentraut committed
374
 <para>
375
  Using <productname>Visual C++ 7.1-8.0</productname> or
376 377 378 379 380 381 382 383 384
  <productname>Borland C++</productname> to build libpq is only recommended
  if you need a version with different debug/release flags, or if you need a
  static library to link into an application. For normal use the
  <productname>MinGW</productname> or
  <productname>Visual Studio 2005</productname> version is recommended.
 </para>

 <para>
  To build the <application>libpq</application> client library using
385
  <productname>Visual Studio 7.1 or later</productname>, change into the
Peter Eisentraut's avatar
Peter Eisentraut committed
386 387 388 389 390
  <filename>src</filename> directory and type the command
<screen>
<userinput>nmake /f win32.mak</userinput>
</screen>
 </para>
391 392 393 394 395 396 397 398 399 400 401
 <para>
 To build a 64-bit version of the <application>libpq</application>
 client library using <productname>Visual Studio 8.0 or
 later</productname>, change into the <filename>src</filename>
 directory and type in the command
<screen>
<userinput>nmake /f win32.mak CPU=AMD64</userinput>
</screen>
 See the <filename>win32.mak</filename> file for further details
 about supported variables.
 </para>
402

403
 <para>
404 405 406
  To build the <application>libpq</application> client library using
  <productname>Borland C++</productname>, change into the
  <filename>src</filename> directory and type the command
407
<screen>
408
<userinput>make -N -DCFG=Release /f bcc32.mak</userinput>
409 410 411
</screen>
 </para>

412 413
 <sect2>
 <title>Generated files</title>
Peter Eisentraut's avatar
Peter Eisentraut committed
414 415
 <para>
  The following files will be built:
416

Peter Eisentraut's avatar
Peter Eisentraut committed
417 418 419 420 421 422 423 424 425 426 427 428 429 430
  <variablelist>
   <varlistentry>
    <term><filename>interfaces\libpq\Release\libpq.dll</filename></term>
    <listitem>
     <para>
      The dynamically linkable frontend library
     </para>
    </listitem>
   </varlistentry>
  
   <varlistentry>
    <term><filename>interfaces\libpq\Release\libpqdll.lib</filename></term>
    <listitem>
     <para>
431
      Import library to link your programs to <filename>libpq.dll</filename>
Peter Eisentraut's avatar
Peter Eisentraut committed
432 433 434
     </para>
    </listitem>
   </varlistentry>
435

Peter Eisentraut's avatar
Peter Eisentraut committed
436 437 438 439
   <varlistentry>
    <term><filename>interfaces\libpq\Release\libpq.lib</filename></term>
    <listitem>
     <para>
440
      Static version of the frontend library
Peter Eisentraut's avatar
Peter Eisentraut committed
441 442 443
     </para>
    </listitem>
   </varlistentry>
444

Peter Eisentraut's avatar
Peter Eisentraut committed
445 446
  </variablelist>
 </para>
447

Peter Eisentraut's avatar
Peter Eisentraut committed
448
 <para>
449 450
  Normally you do not need to install any of the client files. You should
  place the <filename>libpq.dll</filename> file in the same directory
451 452 453 454
  as your applications executable file. Do not install
  <filename>libpq.dll</filename> into your Windows, System or System32
  directory unless absolutely necessary.
  If this file is installed using a setup program, it should
Peter Eisentraut's avatar
Peter Eisentraut committed
455 456 457 458
  be installed with version checking using the
  <symbol>VERSIONINFO</symbol> resource included in the file, to
  ensure that a newer version of the library is not overwritten.
 </para>
459

Peter Eisentraut's avatar
Peter Eisentraut committed
460
 <para>
461
  If you are planning to do development using <application>libpq</application>
462 463 464
  on this machine, you will have to add the
  <filename>src\include</filename> and
  <filename>src\interfaces\libpq</filename> subdirectories of the source
465
  tree to the include path in your compiler's settings.
Peter Eisentraut's avatar
Peter Eisentraut committed
466
 </para>
467

Peter Eisentraut's avatar
Peter Eisentraut committed
468
 <para>
469
  To use the library, you must add the
Peter Eisentraut's avatar
Peter Eisentraut committed
470
  <filename>libpqdll.lib</filename> file to your project.  (In Visual
Peter Eisentraut's avatar
Peter Eisentraut committed
471
  C++, just right-click on the project and choose to add it.)
Peter Eisentraut's avatar
Peter Eisentraut committed
472
 </para>
473 474
 </sect2>
 </sect1>
Peter Eisentraut's avatar
Peter Eisentraut committed
475
</chapter>