doc/src/sgml/install-windows.sgml

   1 <!-- doc/src/sgml/install-windows.sgml -->
   2
   3 <chapter id="install-windows">
   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 graphical installer package
  14   from the <productname>PostgreSQL</productname> website at
  15   <ulink url="https://www.postgresql.org/download/"></ulink>. Building from source
  16   is only intended for people developing <productname>PostgreSQL</productname>
  17   or extensions.
  18  </para>
  19
  20  <para>
  21   There are several different ways of building PostgreSQL on
  22   <productname>Windows</productname>. The simplest way to build with
  23   Microsoft tools is to install <productname>Visual Studio 2022</productname>
  24   and use the included compiler. It is also possible to build with the full
  25   <productname>Microsoft Visual C++ 2015 to 2022</productname>.
  26   In some cases that requires the installation of the
  27   <productname>Windows SDK</productname> in addition to the compiler.
  28  </para>
  29
  30  <para>
  31   It is also possible to build PostgreSQL using the GNU compiler tools
  32   provided by <productname>MinGW</productname>, or using
  33   <productname>Cygwin</productname> for older versions of
  34   <productname>Windows</productname>.
  35  </para>
  36
  37  <para>
  38   Building using <productname>MinGW</productname> or
  39   <productname>Cygwin</productname> uses the normal build system, see
  40   <xref linkend="installation"/> and the specific notes in
  41   <xref linkend="installation-notes-mingw"/> and <xref linkend="installation-notes-cygwin"/>.
  42   To produce native 64 bit binaries in these environments, use the tools from
  43   <productname>MinGW-w64</productname>. These tools can also be used to
  44   cross-compile for 32 bit and 64 bit <productname>Windows</productname>
  45   targets on other hosts, such as <productname>Linux</productname> and
  46   <productname>macOS</productname>.
  47   <productname>Cygwin</productname> is not recommended for running a
  48   production server, and it should only be used for running on
  49   older versions of <productname>Windows</productname> where
  50   the native build does not work. The official
  51   binaries are built using <productname>Visual Studio</productname>.
  52  </para>
  53
  54  <para>
  55   Native builds of <application>psql</application> don't support command
  56   line editing. The <productname>Cygwin</productname> build does support
  57   command line editing, so it should be used where psql is needed for
  58   interactive use on  <productname>Windows</productname>.
  59  </para>
  60
  61  <sect1 id="install-windows-full">
  62   <title>Building with <productname>Visual C++</productname> or the
  63   <productname>Microsoft Windows SDK</productname></title>
  64
  65  <para>
  66   PostgreSQL can be built using the Visual C++ compiler suite from Microsoft.
  67   These compilers can be either from <productname>Visual Studio</productname>,
  68   <productname>Visual Studio Express</productname> or some versions of the
  69   <productname>Microsoft Windows SDK</productname>. If you do not already have a
  70   <productname>Visual Studio</productname> environment set up, the easiest
  71   ways are to use the compilers from
  72   <productname>Visual Studio 2022</productname> or those in the
  73   <productname>Windows SDK 10</productname>, which are both free downloads
  74   from Microsoft.
  75  </para>
  76
  77  <para>
  78   Both 32-bit and 64-bit builds are possible with the Microsoft Compiler suite.
  79   32-bit PostgreSQL builds are possible with
  80   <productname>Visual Studio 2015</productname> to
  81   <productname>Visual Studio 2022</productname>,
  82   as well as standalone Windows SDK releases 10 and above.
  83   64-bit PostgreSQL builds are supported with
  84   <productname>Microsoft Windows SDK</productname> version 10 and above or
  85   <productname>Visual Studio 2015</productname> and above.
  86    <!--
  87        For 2015 requirements:
  88        https://docs.microsoft.com/en-us/visualstudio/productinfo/vs2015-sysrequirements-vs
  89        For 2017 requirements:
  90        https://docs.microsoft.com/en-us/visualstudio/productinfo/vs2017-system-requirements-vs
  91        For 2019 requirements:
  92        https://docs.microsoft.com/en-us/visualstudio/releases/2019/system-requirements
  93        For 2022 requirements:
  94        https://docs.microsoft.com/en-us/visualstudio/releases/2022/system-requirements
  95    -->
  96  </para>
  97
  98  <para>
  99   The tools for building using <productname>Visual C++</productname> or
 100   <productname>Platform SDK</productname> are in the
 101   <filename>src\tools\msvc</filename> directory. When building, make sure
 102   there are no tools from <productname>MinGW</productname> or
 103   <productname>Cygwin</productname> present in your system PATH. Also, make
 104   sure you have all the required Visual C++ tools available in the PATH. In
 105   <productname>Visual Studio</productname>, start the
 106   <application>Visual Studio Command Prompt</application>.
 107   If you wish to build a 64-bit version, you must use the 64-bit version of
 108   the command, and vice versa.
 109   Starting with <productname>Visual Studio 2017</productname> this can be
 110   done from the command line using <command>VsDevCmd.bat</command>, see
 111   <command>-help</command> for the available options and their default values.
 112   <command>vsvars32.bat</command> is available in
 113   <productname>Visual Studio 2015</productname> and earlier versions for the
 114   same purpose.
 115   From the <application>Visual Studio Command Prompt</application>, you can
 116   change the targeted CPU architecture, build type, and target OS by using the
 117   <command>vcvarsall.bat</command> command, e.g.,
 118   <command>vcvarsall.bat x64 10.0.10240.0</command> to target Windows 10
 119   with a 64-bit release build. See <command>-help</command> for the other
 120   options of <command>vcvarsall.bat</command>. All commands should be run from
 121   the <filename>src\tools\msvc</filename> directory.
 122  </para>
 123
 124  <para>
 125   Before you build, you can create the file <filename>config.pl</filename>
 126   to reflect any configuration options you want to change, or the paths to
 127   any third party libraries to use. The complete configuration is determined
 128   by first reading and parsing the file <filename>config_default.pl</filename>,
 129   and then apply any changes from <filename>config.pl</filename>. For example,
 130   to specify the location of your <productname>Python</productname> installation,
 131   put the following in <filename>config.pl</filename>:
 132 <programlisting>
 133 $config->{python} = 'c:\python310';
 134 </programlisting>
 135   You only need to specify those parameters that are different from what's in
 136   <filename>config_default.pl</filename>.
 137  </para>
 138
 139  <para>
 140   If you need to set any other environment variables, create a file called
 141   <filename>buildenv.pl</filename> and put the required commands there. For
 142   example, to add the path for bison when it's not in the PATH, create a file
 143   containing:
 144 <programlisting>
 145 $ENV{PATH}=$ENV{PATH} . ';c:\some\where\bison\bin';
 146 </programlisting>
 147  </para>
 148
 149  <para>
 150   To pass additional command line arguments to the Visual Studio build
 151   command (msbuild or vcbuild):
 152 <programlisting>
 153 $ENV{MSBFLAGS}="/m";
 154 </programlisting>
 155  </para>
 156
 157  <sect2 id="install-windows-full-requirements">
 158   <title>Requirements</title>
 159   <para>
 160    The following additional products are required to build
 161    <productname>PostgreSQL</productname>. Use the
 162    <filename>config.pl</filename> file to specify which directories the libraries
 163    are available in.
 164
 165    <variablelist>
 166     <varlistentry>
 167      <term><productname>Microsoft Windows SDK</productname></term>
 168      <listitem><para>
 169       If your build environment doesn't ship with a supported version of the
 170       <productname>Microsoft Windows SDK</productname> it
 171       is recommended that you upgrade to the latest version (currently
 172       version 10), available for download from
 173       <ulink url="https://www.microsoft.com/download"></ulink>.
 174      </para>
 175      <para>
 176       You must always include the
 177       <application>Windows Headers and Libraries</application> part of the SDK.
 178       If you install a <productname>Windows SDK</productname>
 179       including the <application>Visual C++ Compilers</application>,
 180       you don't need <productname>Visual Studio</productname> to build.
 181       Note that as of Version 8.0a the Windows SDK no longer ships with a
 182       complete command-line build environment.
 183      </para></listitem>
 184     </varlistentry>
 185
 186     <varlistentry>
 187      <term><productname>ActiveState Perl</productname></term>
 188      <listitem><para>
 189       ActiveState Perl is required to run the build generation scripts. MinGW
 190       or Cygwin Perl will not work. It must also be present in the PATH.
 191       Binaries can be downloaded from
 192       <ulink url="https://www.activestate.com"></ulink>
 193       (Note: version 5.14 or later is required,
 194       the free Standard Distribution is sufficient).
 195      </para></listitem>
 196     </varlistentry>
 197
 198    </variablelist>
 199   </para>
 200   <para>
 201    The following additional products are not required to get started,
 202    but are required to build the complete package. Use the
 203    <filename>config.pl</filename> file to specify which directories the libraries
 204    are available in.
 205
 206    <variablelist>
 207     <varlistentry>
 208      <term><productname>ActiveState TCL</productname></term>
 209      <listitem><para>
 210       Required for building <application>PL/Tcl</application> (Note: version
 211       8.4 is required, the free Standard Distribution is sufficient).
 212      </para></listitem>
 213     </varlistentry>
 214
 215     <varlistentry>
 216      <term><productname>Bison</productname> and
 217       <productname>Flex</productname></term>
 218      <listitem>
 219      <para>
 220       <productname>Bison</productname> and <productname>Flex</productname> are
 221       required to build from Git, but not required when building from a release
 222       file. Only <productname>Bison</productname> versions 2.3 and later
 223       will work. <productname>Flex</productname> must be version 2.5.35 or later.
 224      </para>
 225
 226      <para>
 227       Both <productname>Bison</productname> and <productname>Flex</productname>
 228       are included in the <productname>msys</productname> tool suite, available
 229       from <ulink url="http://www.mingw.org/wiki/MSYS"></ulink> as part of the
 230       <productname>MinGW</productname> compiler suite.
 231      </para>
 232
 233      <para>
 234       You will need to add the directory containing
 235       <filename>flex.exe</filename> and <filename>bison.exe</filename> to the
 236       PATH environment variable in <filename>buildenv.pl</filename> unless
 237       they are already in PATH. In the case of MinGW, the directory is the
 238       <filename>\msys\1.0\bin</filename> subdirectory of your MinGW
 239       installation directory.
 240      </para>
 241
 242      <note>
 243       <para>
 244         The Bison distribution from GnuWin32 appears to have a bug that
 245         causes Bison to malfunction when installed in a directory with
 246         spaces in the name, such as the default location on English
 247         installations <filename>C:\Program Files\GnuWin32</filename>.
 248         Consider installing into <filename>C:\GnuWin32</filename> or use the
 249         NTFS short name path to GnuWin32 in your PATH environment setting
 250         (e.g., <filename>C:\PROGRA~1\GnuWin32</filename>).
 251        </para>
 252      </note>
 253
 254      </listitem>
 255     </varlistentry>
 256
 257     <varlistentry>
 258      <term><productname>Diff</productname></term>
 259      <listitem><para>
 260       Diff is required to run the regression tests, and can be downloaded
 261       from <ulink url="http://gnuwin32.sourceforge.net"></ulink>.
 262      </para></listitem>
 263     </varlistentry>
 264
 265     <varlistentry>
 266      <term><productname>Gettext</productname></term>
 267      <listitem><para>
 268       Gettext is required to build with NLS support, and can be downloaded
 269       from <ulink url="http://gnuwin32.sourceforge.net"></ulink>. Note that binaries,
 270       dependencies and developer files are all needed.
 271      </para></listitem>
 272     </varlistentry>
 273
 274     <varlistentry>
 275      <term><productname>MIT Kerberos</productname></term>
 276      <listitem><para>
 277       Required for GSSAPI authentication support. MIT Kerberos can be
 278       downloaded from
 279       <ulink url="https://web.mit.edu/Kerberos/dist/index.html"></ulink>.
 280      </para></listitem>
 281     </varlistentry>
 282
 283     <varlistentry>
 284      <term><productname>libxml2</productname> and
 285       <productname>libxslt</productname></term>
 286      <listitem><para>
 287       Required for XML support. Binaries can be downloaded from
 288       <ulink url="https://zlatkovic.com/pub/libxml"></ulink> or source from
 289       <ulink url="http://xmlsoft.org"></ulink>. Note that libxml2 requires iconv,
 290       which is available from the same download location.
 291      </para></listitem>
 292     </varlistentry>
 293
 294     <varlistentry>
 295      <term><productname>LZ4</productname></term>
 296      <listitem><para>
 297       Required for supporting <productname>LZ4</productname> compression.
 298       Binaries and source can be downloaded from
 299       <ulink url="https://github.com/lz4/lz4/releases"></ulink>.
 300      </para></listitem>
 301     </varlistentry>
 302
 303     <varlistentry>
 304      <term><productname>Zstandard</productname></term>
 305      <listitem><para>
 306       Required for supporting <productname>Zstandard</productname> compression.
 307       Binaries and source can be downloaded from
 308       <ulink url="https://github.com/facebook/zstd/releases"></ulink>.
 309      </para></listitem>
 310     </varlistentry>
 311
 312     <varlistentry>
 313      <term><productname>OpenSSL</productname></term>
 314      <listitem><para>
 315       Required for SSL support. Binaries can be downloaded from
 316       <ulink url="https://slproweb.com/products/Win32OpenSSL.html"></ulink>
 317       or source from <ulink url="https://www.openssl.org"></ulink>.
 318      </para></listitem>
 319     </varlistentry>
 320
 321     <varlistentry>
 322      <term><productname>ossp-uuid</productname></term>
 323      <listitem><para>
 324       Required for UUID-OSSP support (contrib only). Source can be
 325       downloaded from
 326       <ulink url="http://www.ossp.org/pkg/lib/uuid/"></ulink>.
 327      </para></listitem>
 328     </varlistentry>
 329
 330     <varlistentry>
 331      <term><productname>Python</productname></term>
 332      <listitem><para>
 333       Required for building <application>PL/Python</application>. Binaries can
 334       be downloaded from <ulink url="https://www.python.org"></ulink>.
 335      </para></listitem>
 336     </varlistentry>
 337
 338     <varlistentry>
 339      <term><productname>zlib</productname></term>
 340      <listitem><para>
 341       Required for compression support in <application>pg_dump</application>
 342       and <application>pg_restore</application>. Binaries can be downloaded
 343       from <ulink url="https://www.zlib.net"></ulink>.
 344      </para></listitem>
 345     </varlistentry>
 346
 347    </variablelist>
 348   </para>
 349  </sect2>
 350
 351  <sect2 id="install-windows-full-64-bit">
 352   <title>Special Considerations for 64-Bit Windows</title>
 353
 354   <para>
 355    PostgreSQL will only build for the x64 architecture on 64-bit Windows.
 356   </para>
 357
 358   <para>
 359    Mixing 32- and 64-bit versions in the same build tree is not supported.
 360    The build system will automatically detect if it's running in a 32- or
 361    64-bit environment, and build PostgreSQL accordingly. For this reason, it
 362    is important to start the correct command prompt before building.
 363   </para>
 364
 365   <para>
 366    To use a server-side third party library such as <productname>Python</productname> or
 367    <productname>OpenSSL</productname>, this library <emphasis>must</emphasis> also be
 368    64-bit. There is no support for loading a 32-bit library in a 64-bit
 369    server. Several of the third party libraries that PostgreSQL supports may
 370    only be available in 32-bit versions, in which case they cannot be used with
 371    64-bit PostgreSQL.
 372   </para>
 373  </sect2>
 374
 375  <sect2 id="install-windows-full-build">
 376   <title>Building</title>
 377
 378   <para>
 379    To build all of PostgreSQL in release configuration (the default), run the
 380    command:
 381 <screen>
 382 <userinput>build</userinput>
 383 </screen>
 384    To build all of PostgreSQL in debug configuration, run the command:
 385 <screen>
 386 <userinput>build DEBUG</userinput>
 387 </screen>
 388    To build just a single project, for example psql, run the commands:
 389 <screen>
 390 <userinput>build psql</userinput>
 391 <userinput>build DEBUG psql</userinput>
 392 </screen>
 393    To change the default build configuration to debug, put the following
 394    in the <filename>buildenv.pl</filename> file:
 395 <programlisting>
 396 $ENV{CONFIG}="Debug";
 397 </programlisting>
 398   </para>
 399
 400   <para>
 401    It is also possible to build from inside the Visual Studio GUI. In this
 402    case, you need to run:
 403 <screen>
 404 <userinput>perl mkvcbuild.pl</userinput>
 405 </screen>
 406    from the command prompt, and then open the generated
 407    <filename>pgsql.sln</filename> (in the root directory of the source tree)
 408    in Visual Studio.
 409   </para>
 410  </sect2>
 411
 412  <sect2 id="install-windows-full-clean-inst">
 413   <title>Cleaning and Installing</title>
 414
 415   <para>
 416    Most of the time, the automatic dependency tracking in Visual Studio will
 417    handle changed files. But if there have been large changes, you may need
 418    to clean the installation. To do this, simply run the
 419    <filename>clean.bat</filename> command, which will automatically clean out
 420    all generated files. You can also run it with the
 421    <parameter>dist</parameter> parameter, in which case it will behave like
 422    <userinput>make distclean</userinput> and remove the flex/bison output files
 423    as well.
 424   </para>
 425
 426   <para>
 427    By default, all files are written into a subdirectory of the
 428    <filename>debug</filename> or <filename>release</filename> directories. To
 429    install these files using the standard layout, and also generate the files
 430    required to initialize and use the database, run the command:
 431 <screen>
 432 <userinput>install c:\destination\directory</userinput>
 433 </screen>
 434   </para>
 435
 436   <para>
 437    If you want to install only the client applications and
 438    interface libraries, then you can use these commands:
 439 <screen>
 440 <userinput>install c:\destination\directory client</userinput>
 441 </screen>
 442   </para>
 443  </sect2>
 444
 445  <sect2 id="install-windows-full-reg-tests">
 446   <title>Running the Regression Tests</title>
 447
 448   <para>
 449    To run the regression tests, make sure you have completed the build of all
 450    required parts first. Also, make sure that the DLLs required to load all
 451    parts of the system (such as the Perl and Python DLLs for the procedural
 452    languages) are present in the system path. If they are not, set it through
 453    the <filename>buildenv.pl</filename> file. To run the tests, run one of
 454    the following commands from the <filename>src\tools\msvc</filename>
 455    directory:
 456 <screen>
 457 <userinput>vcregress check</userinput>
 458 <userinput>vcregress installcheck</userinput>
 459 <userinput>vcregress plcheck</userinput>
 460 <userinput>vcregress contribcheck</userinput>
 461 <userinput>vcregress modulescheck</userinput>
 462 <userinput>vcregress ecpgcheck</userinput>
 463 <userinput>vcregress isolationcheck</userinput>
 464 <userinput>vcregress bincheck</userinput>
 465 <userinput>vcregress recoverycheck</userinput>
 466 </screen>
 467
 468    To change the schedule used (default is parallel), append it to the
 469    command line like:
 470 <screen>
 471 <userinput>vcregress check serial</userinput>
 472 </screen>
 473
 474    For more information about the regression tests, see
 475    <xref linkend="regress"/>.
 476   </para>
 477
 478   <para>
 479    Running the regression tests on client programs, with
 480    <command>vcregress bincheck</command>, or on recovery tests, with
 481    <command>vcregress recoverycheck</command>, requires an additional Perl module
 482    to be installed:
 483    <variablelist>
 484     <varlistentry>
 485      <term><productname>IPC::Run</productname></term>
 486      <listitem><para>
 487       As of this writing, <literal>IPC::Run</literal> is not included in the
 488       ActiveState Perl installation, nor in the ActiveState Perl Package
 489       Manager (PPM) library. To install, download the
 490       <filename>IPC-Run-&lt;version&gt;.tar.gz</filename> source archive from
 491       <acronym>CPAN</acronym>,
 492       at <ulink url="https://metacpan.org/dist/IPC-Run"></ulink>, and
 493       uncompress. Edit the <filename>buildenv.pl</filename> file, and add a PERL5LIB
 494       variable to point to the <filename>lib</filename> subdirectory from the
 495       extracted archive. For example:
 496 <programlisting>
 497 $ENV{PERL5LIB}=$ENV{PERL5LIB} . ';c:\IPC-Run-0.94\lib';
 498 </programlisting>
 499      </para></listitem>
 500     </varlistentry>
 501    </variablelist>
 502   </para>
 503
 504   <para>
 505    The TAP tests run with <command>vcregress</command> support the
 506    environment variables <varname>PROVE_TESTS</varname>, that is expanded
 507    automatically using the name patterns given, and
 508    <varname>PROVE_FLAGS</varname>. These can be set on a Windows terminal,
 509    before running <command>vcregress</command>:
 510 <programlisting>
 511 set PROVE_FLAGS=--timer --jobs 2
 512 set PROVE_TESTS=t/020*.pl t/010*.pl
 513 </programlisting>
 514    It is also possible to set up those parameters in
 515    <filename>buildenv.pl</filename>:
 516 <programlisting>
 517 $ENV{PROVE_FLAGS}='--timer --jobs 2'
 518 $ENV{PROVE_TESTS}='t/020*.pl t/010*.pl'
 519 </programlisting>
 520   </para>
 521
 522   <para>
 523     Additionally, the behavior of TAP tests can be controlled by a set of
 524     environment variables, see <xref linkend="regress-tap-vars" />.
 525   </para>
 526
 527   <para>
 528    Some of the TAP tests depend on a set of external commands that would
 529    optionally trigger tests related to them. Each one of those variables
 530    can be set or unset in <filename>buildenv.pl</filename>:
 531    <variablelist>
 532     <varlistentry>
 533      <term><varname>GZIP_PROGRAM</varname></term>
 534      <listitem><para>
 535       Path to a <application>gzip</application> command. The default is
 536       <literal>gzip</literal>, which will search for a command by that
 537       name in the configured <envar>PATH</envar>.
 538      </para></listitem>
 539     </varlistentry>
 540
 541     <varlistentry>
 542      <term><varname>LZ4</varname></term>
 543      <listitem><para>
 544       Path to a <application>lz4</application> command. The default is
 545       <literal>lz4</literal>, which will search for a command by that
 546       name in the configured <envar>PATH</envar>.
 547      </para></listitem>
 548     </varlistentry>
 549
 550     <varlistentry>
 551      <term><varname>OPENSSL</varname></term>
 552      <listitem><para>
 553       Path to an <application>openssl</application> command. The default is
 554       <literal>openssl</literal>, which will search for a command by that
 555       name in the configured <envar>PATH</envar>.
 556      </para></listitem>
 557     </varlistentry>
 558
 559     <varlistentry>
 560      <term><varname>TAR</varname></term>
 561      <listitem><para>
 562       Path to a <application>tar</application> command. The default is
 563       <literal>tar</literal>, which will search for a command by that
 564       name in the configured <envar>PATH</envar>.
 565      </para></listitem>
 566     </varlistentry>
 567
 568     <varlistentry>
 569      <term><varname>ZSTD</varname></term>
 570      <listitem><para>
 571       Path to a <application>zstd</application> command. The default is
 572       <literal>zstd</literal>, which will search for a command by that
 573       name in the configured <envar>PATH</envar>.
 574      </para></listitem>
 575     </varlistentry>
 576    </variablelist>
 577   </para>
 578  </sect2>
 579
 580  </sect1>
 581 </chapter>