pg.ddx.io GitHub: postgresql-interfaces/psqlodbc (issues + PRs as email threads)
help / color / mirror / Atom feed[postgresql-interfaces/psqlodbc] PR #234: Rewrite the Windows build page for the current build
3+ messages / 1 participants
[nested] [flat]
* [postgresql-interfaces/psqlodbc] PR #234: Rewrite the Windows build page for the current build
@ 2026-11-04 16:43 "davecramer (@davecramer)" <noreply+davecramer@github.com>
0 siblings, 0 replies; 3+ messages in thread
From: davecramer (@davecramer) @ 2026-11-04 16:43 UTC (permalink / raw)
To: postgresql-interfaces/psqlodbc <noreply+postgresql-interfaces-psqlodbc@github.com>
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.patch
diff --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` |
^ permalink raw [nested|flat] 3+ messages in thread
* Re: [postgresql-interfaces/psqlodbc] PR #234: Rewrite the Windows build page for the current build
@ 2026-11-04 17:51 "davecramer (@davecramer)" <noreply+davecramer@github.com>
1 sibling, 0 replies; 3+ messages in thread
From: davecramer (@davecramer) @ 2026-11-04 17:51 UTC (permalink / raw)
To: postgresql-interfaces/psqlodbc <noreply+postgresql-interfaces-psqlodbc@github.com>
@davecramer merged this (commit 986c6100f8e3).
^ permalink raw [nested|flat] 3+ messages in thread
* Re: [postgresql-interfaces/psqlodbc] PR #234: Rewrite the Windows build page for the current build
@ 2026-11-04 17:51 "davecramer (@davecramer)" <noreply+davecramer@github.com>
1 sibling, 0 replies; 3+ messages in thread
From: davecramer (@davecramer) @ 2026-11-04 17:51 UTC (permalink / raw)
To: postgresql-interfaces/psqlodbc <noreply+postgresql-interfaces-psqlodbc@github.com>
@davecramer closed this.
^ permalink raw [nested|flat] 3+ messages in thread
end of thread, other threads:[~2026-11-04 17:51 UTC | newest]
Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2026-11-04 16:43 [postgresql-interfaces/psqlodbc] PR #234: Rewrite the Windows build page for the current build "davecramer (@davecramer)" <noreply+davecramer@github.com>
2026-11-04 17:51 ` "davecramer (@davecramer)" <noreply+davecramer@github.com>
2026-11-04 17:51 ` "davecramer (@davecramer)" <noreply+davecramer@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