pg.ddx.io  GitHub: postgresql-interfaces/psqlodbc (issues + PRs as email threads)  
help / color / mirror / Atom feed
From: davecramer (@davecramer) <noreply+davecramer@github.com>
To: postgresql-interfaces/psqlodbc <noreply+postgresql-interfaces-psqlodbc@github.com>
Subject: [postgresql-interfaces/psqlodbc] PR #234: Rewrite the Windows build page for the current build
Date: Wed, 04 Nov 2026 16:43:14 +0000
Message-ID: <gh-postgresql-interfaces-psqlodbc-234@github.com> (raw)

Rewrites `website/content/docs/building-windows.md`, which #233 ported unchanged from `docs/win32-compilation.html`.

## What was wrong

- **Visual Studio versions.** It listed Visual Studio 2010 to 2015 and Windows SDK 7.1. The scripts accept `14.0` (VS 2015) to `18.0` (VS 2026), see `winbuild/MSProgram-Get.psm1`.
- **ARM64.** It wasn't mentioned, although `BuildAll.ps1`, `regress.ps1` and `buildInstallers.ps1` all take ARM64, and CI builds and tests it.
- **Output directories.** The list had `x86_ANSI_Release` twice and the ANSI and Unicode labels the wrong way round.
- **The regression test default.** It said the default was 32-bit; it is `both`.
- **SSL DLLs.** It named the bundled SSL DLLs `ssleay32` and `libeay32`, which are OpenSSL 1.0 names.
- **NMAKE.** It documented `nmake /f win64.mak installer`, which was removed in #65, and `SSL_INC` and `SSL_LIB`, which `win64.mak` doesn't read.
- **IDE.** It pointed at `psqlodbc.proj`, which doesn't exist, and at Visual C++ 6.0 and 2005 project files.
- **Links.** The 2ndQuadrant `pg_build_win` link returns 404.

## Where the new content comes from

- **The release workflow** (`.github/workflows/main.yml`): the requirements, WiX 6, libpq built from source for x86 and ARM64, and GNU DiffUtils for the tests.
- **The `Param()` blocks of the scripts.** Each script's `Get-Help` text is out of date (it lists only Win32 and x64, and old toolsets), so the parameter tables follow the code.
- **`psqlodbc.vcxproj` and `.gitignore`:** the output directory names and their location at the top of the source tree.
- **`regress.ps1`:** the test DSN registration, which asks for administrator rights, the `-DsnInfo` prompt, the `-TestList` names, and where `regression.diffs` goes.
- **`buildInstallers.ps1`:** the outputs, when the `psqlodbc-setup.exe` bootstrapper is built, and the runtime options.
- **`win64.mak` and `windows-defaults.mak`:** the NMAKE section, which now builds drivers only. It notes that `world` needs the Windows SDK 7.1 `setenv` command.

The IDE section is gone. The supported build is the scripts, and the old project files describe tools from 2005.

`docs/win32-compilation.html` is unchanged. `readme_winbuild.txt` and the source tarball still refer to it, so it is still out of date there.

## Testing

`hugo --minify` builds with no warnings. The link check finds only the two existing problems from #233: the FAQ's stray `#5.2` and `/backups/`. I looked at the page in a browser.

Assisted-By: Claude

inline patch 1: website/content/docs/building-windows.md (+144/-212 lines) download inline-1.patchdiff --git a/website/content/docs/building-windows.md b/website/content/docs/building-windows.md index 9657fb46..e7bce5e0 100644 --- a/website/content/docs/building-windows.md +++ b/website/content/docs/building-windows.md @@ -5,221 +5,153 @@ aliases: - /docs/win32-compilation.html --- -This page describes how to build the PostgreSQL ODBC Driver on Windows. There are three methods to build: from command line using nmake makefiles, from Powershell using MSBuild files, and from Visual Studio IDE. +psqlODBC is built on Windows with the PowerShell scripts in `winbuild\` and `installer\`, which drive MSBuild and WiX. The official releases are built this way, by the [MSBuild workflow](https://github.com/postgresql-interfaces/psqlodbc/blob/main/.github/workflows/main.yml) in the repository. + +| Script | What it does | +| --- | --- | +| `winbuild\editConfiguration.ps1` | Opens a window for editing the build configuration, `winbuild\configuration.xml` | +| `winbuild\BuildAll.ps1` | Builds the drivers | +| `winbuild\regress.ps1` | Builds the regression tests and runs them against the drivers you built | +| `installer\buildInstallers.ps1` | Builds the `.msi` installers and merge modules | + +Each script has a batch file of the same name at the top of the source tree, such as `BuildAll.bat`, for use from Command Prompt. + +## Requirements + +- **Visual Studio 2015 or later, up to Visual Studio 2026**, with the "Desktop development with C++" workload. Install the MSVC build tools for each platform you build: x86 and x64, and ARM64 for ARM64 builds. The build tools without the IDE are enough. +- **libpq for each platform:** the headers (`include`), the import library (`lib`) and the DLLs (`bin`). The PostgreSQL installers for Windows include 64-bit libpq. For x86 and ARM64 you build libpq from the PostgreSQL source; the release workflow builds it with Meson, with OpenSSL for SSL support. +- **WiX 6 with the UI extension**, to build installers: + + ```powershell + dotnet tool install --global wix --version "6.*" + wix extension add --global WixToolset.UI.wixext/6.0.0 + ``` + +- **The `mimalloc` submodule**, to build with the mimalloc allocator. Clone with `git clone --recurse-submodules`, or run `git submodule update --init` in an existing clone. +- **For the regression tests:** a running PostgreSQL server, and GNU `diff` on `PATH`, for example from [GnuWin32 DiffUtils](https://gnuwin32.sourceforge.net/packages/diffutils.htm), which the release workflow uses. + +PowerShell must be allowed to run local scripts. If `Get-ExecutionPolicy` reports `Restricted` or `AllSigned`, run: + +```powershell +Set-ExecutionPolicy RemoteSigned +``` -The following 3rd party software are required for the build: +## Configuring the build -- Microsoft Windows SDK 7.0 (or later), or Microsoft Visual Studio C++ 2005 Edition (or later). Other compilers may work but have not been tested. Download the latest version from [Microsoft's download page](http://www.microsoft.com/downloads/) -- PostgreSQL Client library (libpq.dll) and headers. Download the latest version from the [PostgreSQL Binaries Download page](http://www.enterprisedb.com/products-services-training/pgbindownload/). -- WiX Toolset. Required for building the installer. Download the latest version from the [WiX Toolset website](http://wixtoolset.org/) +The scripts read the location of libpq for each platform from `winbuild\configuration.xml`. To create or edit it, run: -## Building with Powershell and MSBuild +```powershell +.\winbuild\editConfiguration.ps1 +``` - Using Powershell and MSBuild is recommended. - In fact the binaries of official release are built using this mothod. +or copy `winbuild\configuration_template.xml` to `winbuild\configuration.xml` and edit it by hand. For example: - Currently 4 Windows Powershell scripts are provided for developers. +```xml +<Configuration version="" formatVersion="0.4" vcversion="" toolset=""> + <x86 disabled="no"> + <libpq version="y"> + <include>D:\postgresql86\include</include> + <lib>D:\postgresql86\lib</lib> + <bin>D:\postgresql86\bin</bin> + </libpq> + </x86> + <x64> + <libpq version="y"> + <include>D:\postgresql\include</include> + <lib>D:\postgresql\lib</lib> + <bin>D:\postgresql\bin</bin> + </libpq> + </x64> + <arm64> + <libpq version="y"> + <include>C:\postgresql_arm64\include</include> + <lib>C:\postgresql_arm64\lib</lib> + <bin>C:\postgresql_arm64\bin</bin> + </libpq> + </arm64> +</Configuration> +``` + +Leave `vcversion` and `toolset` empty to use the newest Visual Studio installed. After each build, `BuildAll.ps1` records the Visual Studio version and toolset it used in the `BuildResult` element of this file. + +## Building the drivers + +```powershell +.\winbuild\BuildAll.ps1 +``` + +builds the Release drivers for x86 and x64. The parameters are: + +| Parameter | Values | Default | +| --- | --- | --- | +| `-Platform` | `Win32`, `x64`, `ARM64`, or `both` for Win32 and x64. ARM64 is built only when you ask for it. | `both` | +| `-Configuration` | `Release` or `Debug` | `Release` | +| `-Target` | `Build`, `Rebuild` or `Clean` | `Build` | +| `-VCVersion` | The Visual Studio version, from `14.0` (Visual Studio 2015) to `18.0` (Visual Studio 2026) | the newest installed | +| `-Toolset` | The MSBuild platform toolset, such as `v143` | chosen from the Visual Studio version | +| `-UseMimalloc` | Build with the mimalloc allocator. Needs the `v141` toolset or later, and isn't available for ARM64. | off | +| `-AlongWithInstallers` | Build the installers after the drivers | off | +| `-BuildConfigPath` | A configuration file other than `winbuild\configuration.xml` | | + +For example, to build the ARM64 drivers: + +```powershell +.\winbuild\BuildAll.ps1 -Platform ARM64 +``` + +Each platform, driver type and configuration gets its own output directory, named `<cpu>_<type>_<configuration>`, for example `x64_Unicode_Release` or `arm64_ANSI_Debug`. The directories are created at the top of the source tree, or under the directory in the `PSQLODBC_OBJBASE` environment variable if it is set. Each holds: + +| File | What it is | +| --- | --- | +| `psqlodbc35w.dll` | the Unicode driver (in the `Unicode` directories) | +| `psqlodbc30a.dll` | the ANSI driver (in the `ANSI` directories) | +| `pgenlist.dll`, `pgenlista.dll` | MSDTC support for the Unicode and the ANSI driver | +| `pgxalib.dll` | the MSDTC XA library, built with the Unicode driver and used by both | + +## Running the regression tests + +```powershell +.\winbuild\regress.ps1 -DsnInfo "SERVER=localhost|DATABASE=contrib_regression|PORT=5432|UID=postgres|PWD=password" +``` - winbuild/BuildAll.ps1 - build all dlls for psqlodbc drivers using - MSBuild. - winbuild/editConfiguration.ps1 - a GUI tool to set Build environment - winbuild/regress.ps1 - build regression test programs and run - installer/buildInstallers.ps1 - build installers(.msi and setup.exe) - - Use Powershell console or Command Prompt to invoke scripts: - - For example, to build the driver: - - C:\psqlodbc\winbuild\> (Powershell) ./BuildAll.ps1 <options> - - or you can use the same functionality from Command Prompt using Windows - helper batch at the parent folder (..\). See ..\readme_winbuild.txt. - - C:\psqlodbc\> (Command Prompt) .\BuildAll.bat <options> - - 1. Please start a powershell console and set the ExecutionPolicy of - Powershell to RemoteSigned or Unrestricted. - - You can get the ExecutionPolicy by typing - - Get-ExecutionPolicy - - When the ExecutionPolicy is "Restricted" or "AllSigned" then type e.g. - - Set-ExecutionPolicy RemoteSigned - - To see details about ExecutionPolicy, type - - Get-Help about_Execution_Policies - - 2. You have to install one of the following. - - . Visual Studio 2015 non-Express edtion or Express 2015 for Windows - Desktop - . Visual Studio 2013 non-Express edtion or Express 2013 for Windows - Desktop - . Visual Studio 2012 non-Express edtion or Express 2012 for Windows - Desktop - . Full Microsoft Visual C++ 2010 - . Windows SDK 7.1 - - You have to include x64 development tools (bin, lib, include) as - well as x86 ones for the installation. - - You can install multiple versions of VC++ and use them. - You can easily switch by specifying VCVersion parameter. - - 3. Setup Build environment - - Please type - - .\editConfiguration(.ps1) - - and edit the setting of your environment especially the folders - you placed libpq related include/lib/bin files. - - - - 4. Build - - Please type - - .\BuildAll(.ps1) - - to invoke build operations. - - If you installed both VC10 and VC12 and you'd like to compile - under VC10 environment, type - - .\BuildAll(.ps1) -V(CVersion) 10.0 - - or set the value 10.0 to vcversion using ./editConfiguration. - - To see details about the use of BuildAll, type - - Get-Help .\BuildAll(.ps1) [-Detailed | -Examples | -Full] - - 5. Outputs of Build - - The build can produce output in up to four directories for each of - the debug and release configurations: - - - x64_Unicode_Release the Unicode driver, 64-bit - - x86_ANSI_Release the ANSI driver, 64-bit - - x86_Unicode_Release the ANSI driver, 32-bit - - x86_ANSI_Release the Unicode driver, 32-bit - - For debug builds (-Configuration Debug) the directories are named with - Debug instead of Release but otherwise the same. - - pgxalib.dll is only built for the multibyte/unicode version, as it is - the same for both unicode and ansi drivers. - - 6. How to use drivers. - - You can't use psqlodbc drivers at once you build the drivers. - Usually you have to install drivers using installers made by - installer/buildInstallers.ps1. buildInstallers.ps1 bundles - libpq and related libraries like ssleay32, libeay32 from the - PostgreSQL bin directory and MSVC runtime libraries compiled with. - - However, it is painful for developers to build binaries, build - installers and install each time the source files are changed. - It is recommended to use a special installation-less driver - (postgres_devw) registered by regress.ps1 - - 7. Regression test in place - - After BuildAll(.ps1), please type - - .\regress(.ps1) - - You have to neither install nor copy binaries. - By default, build 32-bit binaries from test sources and run the tests. - If you'd like to test 64-bit version, please type - - .\regress(.ps1) -p(latform) x64 - - Please note the outputs(obj, exe etc) generated by build operations and - results of tests are placed in the directory winbuild/test_x86(test_x64 - in case of 64-bit). - - 8. Installer - - To build the .msi installer file: - - C:\psqlodbc\installer\> (Powershell) ./buildInstallers.ps1 <options> - or - C:\psqlodbc\> (Command Prompt) .\buildInstallers.bat <options> - - By default, buildInstallers.ps1 builds bootstrapper program - psqlodbc-setup.exe together. - - See ../installer/readme.txt in the source directory for details. - - Troubleshooting: - - Some documentation on dealing with Windows SDK installation issues - can be found on the related pg_build_win page: - https://github.com/2ndQuadrant/pg_build_win#troubleshooting - -## Building with nmake.exe - -Use NMAKE.exe to build the driver for the currently active target:\ -\ -`C:\psqlodbc\> nmake /f win64.mak <options>`\ - - -Despite the name, win64.mak is used to build both 32-bit and 64-bit binaries. With the Microsoft Windows SDK Command Prompt, you can switch between 32-bit and 64-bit target architectures with `setenv /x86` and `setenv /x64` commands. If using a Visual Studio Command Prompt you can start the x86 or x64 versions from the Start menu, or run `vcvarsall.bat` with appropriate options to switch architectures. - -To build the .msi installer file:\ -\ -`C:\psqlodbc\> nmake /f win64.mak installer`\ -\ -The resulting installer file goes to installer/x64 or installer/x86 directory. - -To build both 32-bit and 64-bit versions in one command:\ -\ -`C:\psqlodbc\> nmake /f win64.mak world`\ - - -The following build options may be used, either on the command line, or by creating a file called "windows-local.mak". - -| | | -|--------------|----------------------------------------------------------| -| Variable | Values | -| CFG | Release(default), or Debug | -| PG_INC | \$(PROGRAMFILES)\PostgreSQL\9.3\include | -| PG_LIB | \$(PROGRAMFILES)\PostgreSQL\9.3\lib | -| SSL_INC | C:\OpenSSL-Win32\include | -| SSL_LIB | C:\OpenSSL-Win32\lib | -| ANSI_VERSION | no (If set to "yes", output dll name to psqlodbc30a.dll) | -| MSDTC | yes | - -1. UNICODE is the default (psqlodbc35w.dll), unless ANSI_VERSION is selected (psqlodbc30a.dll) -2. libpq.dll is mandatory. -3. If MSDTC == Yes, "pgxalib.dll" is created. -4. If MSDTC is enabled, ANSI_VERSION also creates "pgenlista.dll", or UNICODE creates "pgenlist.dll". - -## IDE Method - -A Microsoft Visual Studio project file (and workspace) is included in the source tree. - -**psqlodbc.dsp** can be used with Microsoft Visual C++ 6.0. - -**psqlodbc.proj** and **psqlodbc.sln** can be used with Microsoft Visual C++ 2005 Edition (including the Express edition which can be downloaded free of charge from <http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/default.aspx;) - -Preparation before the build: - -1. The Windows distribution of PostgreSQL will install the required headers and libraries into C:\Program Files\PostgreSQL\9.2 -2. OpenSSL should be installed into C:\OpenSSL (OpenSSL binaries can be downloaded from <http://www.slproweb.com/products/Win32OpenSSL.html;) - -If you want to change the installation arrangement, it is necessary to edit the project settings. - -Note: - -The default build settings will create the following driver: - -1. UNICODE support. -2. libpq is mandatory. -3. The driver filename is "psqlodbc35w.dll". +builds the test programs and runs them against the drivers that `BuildAll.ps1` built, with no installer needed. The first run registers a test driver and a System DSN, which asks for administrator rights. Without `-DsnInfo`, the script prompts for the server, port, database, user and password. + +| Parameter | Values | Default | +| --- | --- | --- | +| `-Platform` | `Win32`, `x64`, `ARM64` or `both` | `both` | +| `-Ansi` | Test the ANSI drivers instead of the Unicode drivers | off | +| `-DeclareFetch` | Run with Use Declare/Fetch `on`, `off` or `both` | `on` | +| `-TestList` | Run only these tests, named without `-test`, for example `-TestList connect, select` | all tests | +| `-ReinstallDriver` | Register the test driver again | off | + +The test programs and results go in `winbuild\test_x86`, `winbuild\test_x64` or `winbuild\test_arm64`. Differences from the expected output are written to `regression.diffs` there. + +## Building the installers + +```powershell +.\installer\buildInstallers.ps1 +``` + +builds `psqlodbc_x86.msi` and `psqlodbc_x64.msi`, with the matching merge modules (`.msm`), into `installer\x86` and `installer\x64`, or under `PSQLODBC_OBJBASE` if it is set. When it builds both, it also builds the `psqlodbc-setup.exe` bootstrapper. Use `-cpu x86`, `-cpu x64` or `-cpu arm64` to build one platform. + +The installers bundle libpq and the DLLs it depends on, such as the OpenSSL libraries, from the libpq `bin` directory in the configuration, together with the Visual C++ runtime. `-ExcludeRuntime` leaves out the Visual C++ runtime, `-RedistUCRT` bundles the Visual C++ Redistributable, and `-NoPDB` leaves out the debug symbol files. See `installer\README.txt` for more. + +## Building with NMAKE + +`win64.mak` builds the drivers from a Visual Studio Developer Command Prompt, without the PowerShell scripts. It builds for the architecture of the prompt, despite its name. It does not build installers. + +```bat +nmake /f win64.mak +nmake /f win64.mak ANSI_VERSION=yes +nmake /f win64.mak world +``` + +The first builds the Unicode driver and the second the ANSI driver. `world` builds both drivers for x64 and for x86, but it switches architecture with the `setenv` command of the Windows SDK 7.1 command prompt, which Visual Studio's Developer Command Prompt doesn't have. The defaults are in `windows-defaults.mak`. To change them, create `windows-local.mak` in the same directory, or set them on the command line: + +| Variable | Values | Default | +| --- | --- | --- | +| `CFG` | `Release` or `Debug` | `Release` | +| `PG_INC` | The libpq `include` directory | `$(PROGRAMFILES)\PostgreSQL\9.6\include` | +| `PG_LIB` | The libpq `lib` directory | `$(PROGRAMFILES)\PostgreSQL\9.6\lib` | +| `ANSI_VERSION` | `yes` builds the ANSI driver, `psqlodbc30a.dll`, instead of the Unicode driver, `psqlodbc35w.dll` | `no` | +| `MSDTC` | `no` leaves out MSDTC support | `yes` |

view thread (3+ messages)  latest in thread

Message-ID: <gh-postgresql-interfaces-psqlodbc-234@github.com>
Permalink:  ../gh-postgresql-interfaces-psqlodbc-234@github.com/

 ·  · 


This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox