diff options
Diffstat (limited to 'doc/src/sgml/install-windows.sgml')
| -rw-r--r-- | doc/src/sgml/install-windows.sgml | 573 |
1 files changed, 573 insertions, 0 deletions
diff --git a/doc/src/sgml/install-windows.sgml b/doc/src/sgml/install-windows.sgml new file mode 100644 index 0000000..0d7decc --- /dev/null +++ b/doc/src/sgml/install-windows.sgml @@ -0,0 +1,573 @@ +<!-- doc/src/sgml/install-windows.sgml --> + +<chapter id="install-windows"> + <title>Installation from Source Code on <productname>Windows</productname></title> + + <indexterm> + <primary>installation</primary> + <secondary>on Windows</secondary> + </indexterm> + + <para> + It is recommended that most users download the binary distribution for + Windows, available as a graphical installer package + from the <productname>PostgreSQL</productname> website at + <ulink url="https://www.postgresql.org/download/"></ulink>. 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 simplest way to build with + Microsoft tools is to install <productname>Visual Studio 2022</productname> + and use the included compiler. It is also possible to build with the full + <productname>Microsoft Visual C++ 2013 to 2022</productname>. + In some cases that requires the installation of the + <productname>Windows SDK</productname> in addition to the compiler. + </para> + + <para> + It is also possible to build PostgreSQL using the GNU compiler tools + provided by <productname>MinGW</productname>, or using + <productname>Cygwin</productname> for older versions of + <productname>Windows</productname>. + </para> + + <para> + Building using <productname>MinGW</productname> or + <productname>Cygwin</productname> uses the normal build system, see + <xref linkend="installation"/> and the specific notes in + <xref linkend="installation-notes-mingw"/> and <xref linkend="installation-notes-cygwin"/>. + To produce native 64 bit binaries in these environments, use the tools from + <productname>MinGW-w64</productname>. These tools can also be used to + cross-compile for 32 bit and 64 bit <productname>Windows</productname> + targets on other hosts, such as <productname>Linux</productname> and + <productname>macOS</productname>. + <productname>Cygwin</productname> is not recommended for running a + production server, and it should only be used for running on + older versions of <productname>Windows</productname> where + the native build does not work. The official + binaries are built using <productname>Visual Studio</productname>. + </para> + + <para> + Native builds of <application>psql</application> don't support command + line editing. The <productname>Cygwin</productname> build does support + command line editing, so it should be used where psql is needed for + interactive use on <productname>Windows</productname>. + </para> + + <sect1 id="install-windows-full"> + <title>Building with <productname>Visual C++</productname> or the + <productname>Microsoft Windows SDK</productname></title> + + <para> + PostgreSQL can be built using the Visual C++ compiler suite from Microsoft. + These compilers can be either from <productname>Visual Studio</productname>, + <productname>Visual Studio Express</productname> or some versions of the + <productname>Microsoft Windows SDK</productname>. If you do not already have a + <productname>Visual Studio</productname> environment set up, the easiest + ways are to use the compilers from + <productname>Visual Studio 2022</productname> or those in the + <productname>Windows SDK 10</productname>, which are both free downloads + from Microsoft. + </para> + + <para> + Both 32-bit and 64-bit builds are possible with the Microsoft Compiler suite. + 32-bit PostgreSQL builds are possible with + <productname>Visual Studio 2013</productname> to + <productname>Visual Studio 2022</productname>, + as well as standalone Windows SDK releases 8.1a to 10. + 64-bit PostgreSQL builds are supported with + <productname>Microsoft Windows SDK</productname> version 8.1a to 10 or + <productname>Visual Studio 2013</productname> and above. Compilation + is supported down to <productname>Windows 7</productname> and + <productname>Windows Server 2008 R2 SP1</productname> when building with + <productname>Visual Studio 2013</productname> to + <productname>Visual Studio 2022</productname>. + <!-- + For 2013 requirements: + https://docs.microsoft.com/en-us/visualstudio/productinfo/vs2013-sysrequirements-vs + For 2015 requirements: + https://docs.microsoft.com/en-us/visualstudio/productinfo/vs2015-sysrequirements-vs + For 2017 requirements: + https://docs.microsoft.com/en-us/visualstudio/productinfo/vs2017-system-requirements-vs + For 2019 requirements: + https://docs.microsoft.com/en-us/visualstudio/releases/2019/system-requirements + For 2022 requirements: + https://docs.microsoft.com/en-us/visualstudio/releases/2022/system-requirements + --> + </para> + + <para> + The tools for building using <productname>Visual C++</productname> or + <productname>Platform SDK</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. In + <productname>Visual Studio</productname>, start the + <application>Visual Studio Command Prompt</application>. + If you wish to build a 64-bit version, you must use the 64-bit version of + the command, and vice versa. + Starting with <productname>Visual Studio 2017</productname> this can be + done from the command line using <command>VsDevCmd.bat</command>, see + <command>-help</command> for the available options and their default values. + <command>vsvars32.bat</command> is available in + <productname>Visual Studio 2015</productname> and earlier versions for the + same purpose. + From the <application>Visual Studio Command Prompt</application>, you can + change the targeted CPU architecture, build type, and target OS by using the + <command>vcvarsall.bat</command> command, e.g., + <command>vcvarsall.bat x64 10.0.10240.0</command> to target Windows 10 + with a 64-bit release build. See <command>-help</command> for the other + options of <command>vcvarsall.bat</command>. All commands should be run from + the <filename>src\tools\msvc</filename> directory. + </para> + + <para> + Before you build, you can create the file <filename>config.pl</filename> + to reflect any configuration options you want to change, or the paths to + any third party libraries to use. The complete configuration is determined + by first reading and parsing the file <filename>config_default.pl</filename>, + and then apply any changes from <filename>config.pl</filename>. For example, + to specify the location of your <productname>Python</productname> installation, + put the following in <filename>config.pl</filename>: +<programlisting> +$config->{python} = 'c:\python310'; +</programlisting> + You only need to specify those parameters that are different from what's in + <filename>config_default.pl</filename>. + </para> + + <para> + If you need to set any other environment variables, create a file called + <filename>buildenv.pl</filename> and put the required commands there. For + example, to add the path for bison when it's not in the PATH, create a file + containing: +<programlisting> +$ENV{PATH}=$ENV{PATH} . ';c:\some\where\bison\bin'; +</programlisting> + </para> + + <para> + To pass additional command line arguments to the Visual Studio build + command (msbuild or vcbuild): +<programlisting> +$ENV{MSBFLAGS}="/m"; +</programlisting> + </para> + + <sect2> + <title>Requirements</title> + <para> + The following additional products are required to build + <productname>PostgreSQL</productname>. Use the + <filename>config.pl</filename> file to specify which directories the libraries + are available in. + + <variablelist> + <varlistentry> + <term><productname>Microsoft Windows SDK</productname></term> + <listitem><para> + If your build environment doesn't ship with a supported version of the + <productname>Microsoft Windows SDK</productname> it + is recommended that you upgrade to the latest version (currently + version 10), available for download from + <ulink url="https://www.microsoft.com/download"></ulink>. + </para> + <para> + You must always include the + <application>Windows Headers and Libraries</application> part of the SDK. + If you install a <productname>Windows SDK</productname> + including the <application>Visual C++ Compilers</application>, + you don't need <productname>Visual Studio</productname> to build. + Note that as of Version 8.0a the Windows SDK no longer ships with a + complete command-line build environment. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><productname>ActiveState Perl</productname></term> + <listitem><para> + ActiveState Perl is required to run the build generation scripts. MinGW + or Cygwin Perl will not work. It must also be present in the PATH. + Binaries can be downloaded from + <ulink url="https://www.activestate.com"></ulink> + (Note: version 5.8.3 or later is required, + the free Standard Distribution is sufficient). + </para></listitem> + </varlistentry> + + </variablelist> + </para> + <para> + The following additional products are not required to get started, + but are required to build the complete package. Use the + <filename>config.pl</filename> file to specify which directories the libraries + are available in. + + <variablelist> + <varlistentry> + <term><productname>ActiveState TCL</productname></term> + <listitem><para> + Required for building <application>PL/Tcl</application> (Note: version + 8.4 is required, the free Standard Distribution is sufficient). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><productname>Bison</productname> and + <productname>Flex</productname></term> + <listitem> + <para> + <productname>Bison</productname> and <productname>Flex</productname> are + required to build from Git, but not required when building from a release + file. Only <productname>Bison</productname> 1.875 or versions 2.2 and later + will work. <productname>Flex</productname> must be version 2.5.31 or later. + </para> + + <para> + Both <productname>Bison</productname> and <productname>Flex</productname> + are included in the <productname>msys</productname> tool suite, available + from <ulink url="http://www.mingw.org/wiki/MSYS"></ulink> as part of the + <productname>MinGW</productname> compiler suite. + </para> + + <para> + You will need to add the directory containing + <filename>flex.exe</filename> and <filename>bison.exe</filename> to the + PATH environment variable in <filename>buildenv.pl</filename> unless + they are already in PATH. In the case of MinGW, the directory is the + <filename>\msys\1.0\bin</filename> subdirectory of your MinGW + installation directory. + </para> + + <note> + <para> + The Bison distribution from GnuWin32 appears to have a bug that + causes Bison to malfunction when installed in a directory with + spaces in the name, such as the default location on English + installations <filename>C:\Program Files\GnuWin32</filename>. + Consider installing into <filename>C:\GnuWin32</filename> or use the + NTFS short name path to GnuWin32 in your PATH environment setting + (e.g., <filename>C:\PROGRA~1\GnuWin32</filename>). + </para> + </note> + + </listitem> + </varlistentry> + + <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"></ulink>. + </para></listitem> + </varlistentry> + + <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"></ulink>. Note that binaries, + dependencies and developer files are all needed. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><productname>MIT Kerberos</productname></term> + <listitem><para> + Required for GSSAPI authentication support. MIT Kerberos can be + downloaded from + <ulink url="https://web.mit.edu/Kerberos/dist/index.html"></ulink>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><productname>libxml2</productname> and + <productname>libxslt</productname></term> + <listitem><para> + Required for XML support. Binaries can be downloaded from + <ulink url="https://zlatkovic.com/pub/libxml"></ulink> or source from + <ulink url="http://xmlsoft.org"></ulink>. Note that libxml2 requires iconv, + which is available from the same download location. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><productname>LZ4</productname></term> + <listitem><para> + Required for supporting <productname>LZ4</productname> compression. + Binaries and source can be downloaded from + <ulink url="https://github.com/lz4/lz4/releases"></ulink>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><productname>Zstandard</productname></term> + <listitem><para> + Required for supporting <productname>Zstandard</productname> compression. + Binaries and source can be downloaded from + <ulink url="https://github.com/facebook/zstd/releases"></ulink>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><productname>OpenSSL</productname></term> + <listitem><para> + Required for SSL support. Binaries can be downloaded from + <ulink url="https://slproweb.com/products/Win32OpenSSL.html"></ulink> + or source from <ulink url="https://www.openssl.org"></ulink>. + </para></listitem> + </varlistentry> + + <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/"></ulink>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><productname>Python</productname></term> + <listitem><para> + Required for building <application>PL/Python</application>. Binaries can + be downloaded from <ulink url="https://www.python.org"></ulink>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><productname>zlib</productname></term> + <listitem><para> + Required for compression support in <application>pg_dump</application> + and <application>pg_restore</application>. Binaries can be downloaded + from <ulink url="https://www.zlib.net"></ulink>. + </para></listitem> + </varlistentry> + + </variablelist> + </para> + </sect2> + + <sect2> + <title>Special Considerations for 64-Bit Windows</title> + + <para> + PostgreSQL will only build for the x64 architecture on 64-bit Windows, there + is no support for Itanium processors. + </para> + + <para> + Mixing 32- and 64-bit versions in the same build tree is not supported. + The build system will automatically detect if it's running in a 32- or + 64-bit environment, and build PostgreSQL accordingly. For this reason, it + is important to start the correct command prompt before building. + </para> + + <para> + To use a server-side third party library such as <productname>Python</productname> or + <productname>OpenSSL</productname>, this library <emphasis>must</emphasis> also be + 64-bit. There is no support for loading a 32-bit library in a 64-bit + server. Several of the third party libraries that PostgreSQL supports may + only be available in 32-bit versions, in which case they cannot be used with + 64-bit PostgreSQL. + </para> + </sect2> + + <sect2> + <title>Building</title> + + <para> + To build all of PostgreSQL in release configuration (the default), run the + command: +<screen> +<userinput>build</userinput> +</screen> + To build all of PostgreSQL in debug configuration, run the command: +<screen> +<userinput>build DEBUG</userinput> +</screen> + To build just a single project, for example psql, run the commands: +<screen> +<userinput>build psql</userinput> +<userinput>build DEBUG psql</userinput> +</screen> + To change the default build configuration to debug, put the following + in the <filename>buildenv.pl</filename> file: +<programlisting> +$ENV{CONFIG}="Debug"; +</programlisting> + </para> + + <para> + It is also possible to build from inside the Visual Studio GUI. In this + case, you need to run: +<screen> +<userinput>perl mkvcbuild.pl</userinput> +</screen> + from the command prompt, and then open the generated + <filename>pgsql.sln</filename> (in the root directory of the source tree) + in Visual Studio. + </para> + </sect2> + + <sect2> + <title>Cleaning and Installing</title> + + <para> + Most of the time, the automatic dependency tracking in Visual Studio will + 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 + all generated files. You can also run it with the + <parameter>dist</parameter> parameter, in which case it will behave like + <userinput>make distclean</userinput> and remove the flex/bison output files + as well. + </para> + + <para> + By default, all files are written into a subdirectory of the + <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: +<screen> +<userinput>install c:\destination\directory</userinput> +</screen> + </para> + + <para> + If you want to install only the client applications and + interface libraries, then you can use these commands: +<screen> +<userinput>install c:\destination\directory client</userinput> +</screen> + </para> + </sect2> + + <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 + 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 + the <filename>buildenv.pl</filename> file. To run the tests, run one of + the following commands from the <filename>src\tools\msvc</filename> + directory: +<screen> +<userinput>vcregress check</userinput> +<userinput>vcregress installcheck</userinput> +<userinput>vcregress plcheck</userinput> +<userinput>vcregress contribcheck</userinput> +<userinput>vcregress modulescheck</userinput> +<userinput>vcregress ecpgcheck</userinput> +<userinput>vcregress isolationcheck</userinput> +<userinput>vcregress bincheck</userinput> +<userinput>vcregress recoverycheck</userinput> +</screen> + + To change the schedule used (default is parallel), append it to the + command line like: +<screen> +<userinput>vcregress check serial</userinput> +</screen> + + For more information about the regression tests, see + <xref linkend="regress"/>. + </para> + + <para> + Running the regression tests on client programs, with + <command>vcregress bincheck</command>, or on recovery tests, with + <command>vcregress recoverycheck</command>, requires an additional Perl module + to be installed: + <variablelist> + <varlistentry> + <term><productname>IPC::Run</productname></term> + <listitem><para> + As of this writing, <literal>IPC::Run</literal> is not included in the + ActiveState Perl installation, nor in the ActiveState Perl Package + Manager (PPM) library. To install, download the + <filename>IPC-Run-<version>.tar.gz</filename> source archive from CPAN, + at <ulink url="https://metacpan.org/release/IPC-Run"></ulink>, and + uncompress. Edit the <filename>buildenv.pl</filename> file, and add a PERL5LIB + variable to point to the <filename>lib</filename> subdirectory from the + extracted archive. For example: +<programlisting> +$ENV{PERL5LIB}=$ENV{PERL5LIB} . ';c:\IPC-Run-0.94\lib'; +</programlisting> + </para></listitem> + </varlistentry> + </variablelist> + </para> + + <para> + The TAP tests run with <command>vcregress</command> support the + environment variables <varname>PROVE_TESTS</varname>, that is expanded + automatically using the name patterns given, and + <varname>PROVE_FLAGS</varname>. These can be set on a Windows terminal, + before running <command>vcregress</command>: +<programlisting> +set PROVE_FLAGS=--timer --jobs 2 +set PROVE_TESTS=t/020*.pl t/010*.pl +</programlisting> + It is also possible to set up those parameters in + <filename>buildenv.pl</filename>: +<programlisting> +$ENV{PROVE_FLAGS}='--timer --jobs 2' +$ENV{PROVE_TESTS}='t/020*.pl t/010*.pl' +</programlisting> + </para> + + <para> + Some of the TAP tests depend on a set of external commands that would + optionally trigger tests related to them. Each one of those variables + can be set or unset in <filename>buildenv.pl</filename>: + <variablelist> + <varlistentry> + <term><varname>GZIP_PROGRAM</varname></term> + <listitem><para> + Path to a <application>gzip</application> command. The default is + <literal>gzip</literal>, which will search for a command by that + name in the configured <envar>PATH</envar>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LZ4</varname></term> + <listitem><para> + Path to a <application>lz4</application> command. The default is + <literal>lz4</literal>, which will search for a command by that + name in the configured <envar>PATH</envar>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TAR</varname></term> + <listitem><para> + Path to a <application>tar</application> command. The default is + <literal>tar</literal>, which will search for a command by that + name in the configured <envar>PATH</envar>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ZSTD</varname></term> + <listitem><para> + Path to a <application>zstd</application> command. The default is + <literal>zstd</literal>, which will search for a command by that + name in the configured <envar>PATH</envar>. + </para></listitem> + </varlistentry> + </variablelist> + </para> + </sect2> + + </sect1> +</chapter> |