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