Adding upstream version 16.2.upstream/16.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 589 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..f959d27
--- /dev/null
+++ b/doc/src/sgml/install-windows.sgml
@@ -0,0 +1,589 @@
+<!-- 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++ 2015 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 2015</productname> to
+  <productname>Visual Studio 2022</productname>,
+  as well as standalone Windows SDK releases 10 and above.
+  64-bit PostgreSQL builds are supported with
+  <productname>Microsoft Windows SDK</productname> version 10 and above or
+  <productname>Visual Studio 2015</productname> and above.
+   <!--
+       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 id="install-windows-full-requirements">
+  <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.14 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> versions 2.3 and later
+      will work. <productname>Flex</productname> must be version 2.5.35 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 id="install-windows-full-64-bit">
+  <title>Special Considerations for 64-Bit Windows</title>
+
+  <para>
+   PostgreSQL will only build for the x64 architecture on 64-bit Windows.
+  </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 id="install-windows-full-build">
+  <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 id="install-windows-full-clean-inst">
+  <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 id="install-windows-full-reg-tests">
+  <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>
+<userinput>vcregress taptest</userinput>
+</screen>
+
+   To change the schedule used (default is parallel), append it to the
+   command line like:
+<screen>
+<userinput>vcregress check serial</userinput>
+</screen>
+
+   <command>vcregress taptest</command> can be used to run the TAP tests
+   of a target directory, like:
+<screen>
+<userinput>vcregress taptest src\bin\initdb\</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>, on recovery tests with
+   <command>vcregress recoverycheck</command>, or TAP tests specified with
+   <command>vcregress taptest</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-&lt;version&gt;.tar.gz</filename> source archive from
+      <acronym>CPAN</acronym>,
+      at <ulink url="https://metacpan.org/dist/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>
+    Additionally, the behavior of TAP tests can be controlled by a set of
+    environment variables, see <xref linkend="regress-tap-vars" />.
+  </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>OPENSSL</varname></term>
+     <listitem><para>
+      Path to an <application>openssl</application> command. The default is
+      <literal>openssl</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>