Postgresql 中文操作指南

18.1. Building with Visual C++ or the Microsoft Windows SDK #

PostgreSQL 可使用 Microsoft 的 Visual C++ 编译器套件构建。这些编译器可以来自 Visual Studio、Visual Studio Express 或某些版本的 Microsoft Windows SDK。如果您尚未设置好 Visual Studio 环境，最简单的做法是使用 Visual Studio 2022 的编译器或 Windows SDK 10 中的编译器，这两者都可以从 Microsoft 免费下载。

PostgreSQL can be built using the Visual C++ compiler suite from Microsoft. These compilers can be either from Visual Studio, Visual Studio Express or some versions of the Microsoft Windows SDK. If you do not already have a Visual Studio environment set up, the easiest ways are to use the compilers from Visual Studio 2022 or those in the Windows SDK 10, which are both free downloads from Microsoft.

Microsoft 编译器套件支持进行 32 位和 64 位的编译。32 位 PostgreSQL 编译可以使用 Visual Studio 2015 到 Visual Studio 2022，以及独立的 Windows SDK 10 及更高版本。64 位 PostgreSQL 编译受 Microsoft Windows SDK 10 及更高版本或 Visual Studio 2015 及更高版本支持。

Both 32-bit and 64-bit builds are possible with the Microsoft Compiler suite. 32-bit PostgreSQL builds are possible with Visual Studio 2015 to Visual Studio 2022, as well as standalone Windows SDK releases 10 and above. 64-bit PostgreSQL builds are supported with Microsoft Windows SDK version 10 and above or Visual Studio 2015 and above.

使用 Visual C 或 Platform SDK 构建的工具位于 src\tools\msvc 目录中。在构建时，请确保您的系统 PATH 中不包含 MinGW 或 Cygwin 的工具。此外，请确保 PATH 中提供了所有必需的 Visual C 工具。在 Visual Studio 中，启动 Visual Studio 命令提示符。如果您希望构建 64 位版本，您必须使用 64 位版本的该命令，反之亦然。从 Visual Studio 2017 开始，您可以使用 VsDevCmd.bat 通过命令行进行此操作，有关可用选项及其默认值，请参阅 -help。对于相同的目的，vsvars32.bat 在 Visual Studio 2015 和更早版本中可用。在 Visual Studio 命令提示符中，您可以使用 vcvarsall.bat 命令更改目标 CPU 架构、构建类型和目标操作系统，例如，vcvarsall.bat x64 10.0.10240.0 来以 64 位发布构建方式为目标锁定 Windows 10。有关其他 vcvarsall.bat 选项，请参阅 -help。所有命令都应当从 src\tools\msvc 目录运行。

The tools for building using Visual C or Platform SDK are in the src\tools\msvc directory. When building, make sure there are no tools from MinGW or Cygwin present in your system PATH. Also, make sure you have all the required Visual C tools available in the PATH. In Visual Studio, start the Visual Studio Command Prompt. If you wish to build a 64-bit version, you must use the 64-bit version of the command, and vice versa. Starting with Visual Studio 2017 this can be done from the command line using VsDevCmd.bat, see -help for the available options and their default values. vsvars32.bat is available in Visual Studio 2015 and earlier versions for the same purpose. From the Visual Studio Command Prompt, you can change the targeted CPU architecture, build type, and target OS by using the vcvarsall.bat command, e.g., vcvarsall.bat x64 10.0.10240.0 to target Windows 10 with a 64-bit release build. See -help for the other options of vcvarsall.bat. All commands should be run from the src\tools\msvc directory.

在您进行构建之前，您可以创建 config.pl 文件，以反映您想要更改的任何配置选项，或指向要使用任何第三方库的路径。完整配置的确定过程首先是读取并解析 config_default.pl 文件，然后再应用 config.pl 中的任何更改。例如，要指定您的 Python 安装位置，请将以下内容放入 config.pl 中：

Before you build, you can create the file config.pl 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 config_default.pl, and then apply any changes from config.pl. For example, to specify the location of your Python installation, put the following in config.pl:

$config->{python} = 'c:\python310';

您只需要指定与 config_default.pl 中内容不同的那些参数。

You only need to specify those parameters that are different from what’s in config_default.pl.

如果您需要设置任何其他环境变量，请创建一个名为 buildenv.pl 的文件并将其中的必需命令。例如，要在 PATH 中不存在 bison 时添加 bison 的路径，请创建一个包含以下内容的文件：

If you need to set any other environment variables, create a file called buildenv.pl 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:

$ENV{PATH}=$ENV{PATH} . ';c:\some\where\bison\bin';

要将附加命令行参数传递给 Visual Studio 构建命令 (msbuild 或 vcbuild)：

To pass additional command line arguments to the Visual Studio build command (msbuild or vcbuild):

$ENV{MSBFLAGS}="/m";

18.1.1. Requirements #

要构建 PostgreSQL，还需要以下其他产品。使用 config.pl 文件指定库的可用目录。

The following additional products are required to build PostgreSQL. Use the config.pl file to specify which directories the libraries are available in.

  • Microsoft Windows SDK

    • If your build environment doesn’t ship with a supported version of the Microsoft Windows SDK it is recommended that you upgrade to the latest version (currently version 10), available for download from https://www.microsoft.com/download.

    • You must always include the Windows Headers and Libraries part of the SDK. If you install a Windows SDK including the Visual C++ Compilers, you don’t need Visual Studio to build. Note that as of Version 8.0a the Windows SDK no longer ships with a complete command-line build environment.

  • ActiveState Perl

    • 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 https://www.activestate.com (Note: version 5.14 or later is required, the free Standard Distribution is sufficient).

以下其他产品不是入门必备的，但构建完整软件包需要它们。使用 config.pl 文件指定库的可用目录。

The following additional products are not required to get started, but are required to build the complete package. Use the config.pl file to specify which directories the libraries are available in.

  • ActiveState TCL

    • Required for building PL/Tcl (Note: version 8.4 is required, the free Standard Distribution is sufficient).

  • Bison and Flex

    • Bison and Flex are required to build from Git, but not required when building from a release file. Only Bison versions 2.3 and later will work. Flex must be version 2.5.35 or later.

    • Both Bison and Flex are included in the msys tool suite, available from http://www.mingw.org/wiki/MSYS as part of the MinGW compiler suite.

    • You will need to add the directory containing flex.exe and bison.exe to the PATH environment variable in buildenv.pl unless they are already in PATH. In the case of MinGW, the directory is the \msys\1.0\bin subdirectory of your MinGW installation directory.

  • Diff

  • Gettext

    • Gettext is required to build with NLS support, and can be downloaded from http://gnuwin32.sourceforge.net. Note that binaries, dependencies and developer files are all needed.

  • MIT Kerberos

  • libxml2 and libxslt

  • LZ4

  • Zstandard

  • OpenSSL

  • ossp-uuid

  • Python

  • zlib

    • Required for compression support in pg_dump and pg_restore. Binaries can be downloaded from https://www.zlib.net.

Note

来自 GnuWin32 的 Bison 分发似乎存在一个缺陷，即当 Bison 安装在名称中带有空格的目录（如英语安装中的默认位置 C:\Program Files\GnuWin32）中时，会导致 Bison 发生故障。考虑安装到 C:\GnuWin32 或在您的 PATH 环境设置中对 GnuWin32 使用 NTFS 短名称路径（例如 C:\PROGRA~1\GnuWin32）。

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 C:\Program Files\GnuWin32. Consider installing into C:\GnuWin32 or use the NTFS short name path to GnuWin32 in your PATH environment setting (e.g., C:\PROGRA~1\GnuWin32).

18.1.2. Special Considerations for 64-Bit Windows #

PostgreSQL 仅针对 64 位 Windows 中的 x64 架构进行编译。

PostgreSQL will only build for the x64 architecture on 64-bit Windows.

构建树中 32 位和 64 位版本的混合是不受支持的。构建系统会自动检测它是在 32 位还是 64 位环境中运行，并相应地构建 PostgreSQL。因此，在构建前启动正确的命令提示很重要。

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.

要使用服务器端第三方库（例如 Python 或 OpenSSL），此库 must 也必须是 64 位。不支持在 64 位服务器中加载 32 位库。PostgreSQL 支持的几个第三方库可能仅提供 32 位版本，在这种情况下，它们不能与 64 位 PostgreSQL 一起使用。

To use a server-side third party library such as Python or OpenSSL, this library must 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.

18.1.3. Building #

要在发布配置（默认）中构建全部 PostgreSQL，请运行以下命令：

To build all of PostgreSQL in release configuration (the default), run the command:

build

要在调试配置中构建全部 PostgreSQL，请运行以下命令：

To build all of PostgreSQL in debug configuration, run the command:

build DEBUG

仅构建一个项目，例如 psql，请运行以下命令：

To build just a single project, for example psql, run the commands:

build psql
build DEBUG psql

要将默认构建配置更改为调试，请将以下内容放入 buildenv.pl 文件中：

To change the default build configuration to debug, put the following in the buildenv.pl file:

$ENV{CONFIG}="Debug";

也可以从 Visual Studio GUI 内部进行编译。在这种情况下，需要执行以下操作：

It is also possible to build from inside the Visual Studio GUI. In this case, you need to run:

perl mkvcbuild.pl

在命令提示符中，然后在 Visual Studio 中打开已生成的 pgsql.sln（在源树的根目录中）。

from the command prompt, and then open the generated pgsql.sln (in the root directory of the source tree) in Visual Studio.

18.1.4. Cleaning and Installing #

大多数情况下，Visual Studio 中的自动依赖项跟踪将处理已更改的文件。但如果发生了较大的更改，您可能需要清除该安装。若要执行此操作，只需运行 clean.bat 命令即可，该命令将自动清除所有生成的文件。您还可以使用 dist 参数运行它，在这种情况下，它将像 make distclean 一样工作，并移除 flex 和 bison 输出文件。

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 clean.bat command, which will automatically clean out all generated files. You can also run it with the dist parameter, in which case it will behave like make distclean and remove the flex/bison output files as well.

默认情况下，所有文件都会写入 debug 或 release 目录的子目录中。若要使用标准布局安装这些文件，还要生成初始化和使用数据库所需的文件，请运行以下命令：

By default, all files are written into a subdirectory of the debug or release directories. To install these files using the standard layout, and also generate the files required to initialize and use the database, run the command:

install c:\destination\directory

如果你只想安装客户端应用程序和接口库，则可以使用以下命令：

If you want to install only the client applications and interface libraries, then you can use these commands:

install c:\destination\directory client

18.1.5. Running the Regression Tests #

为运行回归测试，请确保先完成所有必需部分的构建。此外，确保系统路径中存在加载系统所有部分所需的 DLL（如用于过程语言的 Perl 和 Python DLL）。如果它们不存在，请通过 buildenv.pl 文件进行设置。若要运行测试，请从 src\tools\msvc 目录运行以下命令之一：

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 buildenv.pl file. To run the tests, run one of the following commands from the src\tools\msvc directory:

vcregress check
vcregress installcheck
vcregress plcheck
vcregress contribcheck
vcregress modulescheck
vcregress ecpgcheck
vcregress isolationcheck
vcregress bincheck
vcregress recoverycheck
vcregress taptest

若要更改所使用的计划（默认为并行），请将其附加到命令行，如下所示：

To change the schedule used (default is parallel), append it to the command line like:

vcregress check serial

vcregress taptest 可用于运行目标目录的 TAP 测试，例如：

vcregress taptest can be used to run the TAP tests of a target directory, like:

vcregress taptest src\bin\initdb\

有关回归测试的更多信息，请参阅 Chapter 33。

For more information about the regression tests, see Chapter 33.

使用 vcregress bincheck 对客户端程序运行回归测试，或使用 vcregress recoverycheck 对恢复测试运行回归测试，或使用 vcregress taptest 指定的 TAP 测试，需要安装其他 Perl 模块：

Running the regression tests on client programs with vcregress bincheck, on recovery tests with vcregress recoverycheck, or TAP tests specified with vcregress taptest requires an additional Perl module to be installed:

  • IPC::Run

    • As of this writing, IPC::Run is not included in the ActiveState Perl installation, nor in the ActiveState Perl Package Manager (PPM) library. To install, download the IPC-Run-<version>.tar.gz source archive from CPAN, at https://metacpan.org/dist/IPC-Run, and uncompress. Edit the buildenv.pl file, and add a PERL5LIB variable to point to the lib subdirectory from the extracted archive. For example:

$ENV{PERL5LIB}=$ENV{PERL5LIB} . ';c:\IPC-Run-0.94\lib';

使用 vcregress 运行的 TAP 测试支持环境变量 PROVE_TESTS（使用给定的名称模式自动扩展），和 PROVE_FLAGS。这些可以在运行 vcregress 之前，在 Windows 终端上设置：

The TAP tests run with vcregress support the environment variables PROVE_TESTS, that is expanded automatically using the name patterns given, and PROVE_FLAGS. These can be set on a Windows terminal, before running vcregress:

set PROVE_FLAGS=--timer --jobs 2
set PROVE_TESTS=t/020*.pl t/010*.pl

也可以在 buildenv.pl 中设置这些参数：

It is also possible to set up those parameters in buildenv.pl:

$ENV{PROVE_FLAGS}='--timer --jobs 2'
$ENV{PROVE_TESTS}='t/020*.pl t/010*.pl'

此外，TAP 测试的行为可以通过一组环境变量进行控制，参见 Section 33.4.1。

Additionally, the behavior of TAP tests can be controlled by a set of environment variables, see Section 33.4.1.

一些 TAP 测试依赖于一组外部命令，这些命令可以有选择地触发与其相关的测试。这些变量的每一个都可以在 buildenv.pl 中设置或取消设置：

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 buildenv.pl:

  • GZIP_PROGRAM

    • Path to a gzip command. The default is gzip, which will search for a command by that name in the configured PATH.

  • LZ4

    • Path to a lz4 command. The default is lz4, which will search for a command by that name in the configured PATH.

  • OPENSSL

    • Path to an openssl command. The default is openssl, which will search for a command by that name in the configured PATH.

  • TAR

    • Path to a tar command. The default is tar, which will search for a command by that name in the configured PATH.

  • ZSTD

    • Path to a zstd command. The default is zstd, which will search for a command by that name in the configured PATH.