PQXX is the official C++ client API for PostgreSQL. Build the libpqxx library for Windows quickly, with both Debug and Release configurations, install in Program Files, fix problems, create property sheets to easily use in Visual Studio applications, with named versions for configurations and options. Skip past the notes to Easy-PQXX Batch Build for Visual Studio to jump right in with:
- Automated batch file to build and install in the selected location (typically C:\Program Files\libpqxx), asking for administrator privileges if needed to copy the files.
- EASY_PATCH settings for compile flags for features that are not enabled by CMake, allowing more efficient code in Windows.
- Configure for Unicode or MultiByte character sets. (For example Unicode character set may be needed to interface wxWidgets in the same application.)
- Keep named installations for different configurations.
- One library installation with both Debug and Release compiles that automatically switch in Visual Studio.
- Property Sheets so your Visual Studio application (with both Debug and Release compiles) can be instantly configured.
- Gather DLLs from PostgreSQL library into your application automatically.
Additionally various configuration solving selections can be made, for example if you have more than one PostgreSQL library or want to compile for more than one version of Visual Studio. Sometimes the basic CMake default process does not work out with an ideal result.
The new libpqxx version 7 and
beyond can most easily be built for Windows Visual Studio using the "CMake"
build process. Since version 7 requires C++ 17 standard, to build for
Microsoft Visual Studio the 2017 version of Visual Studio or later is
required. And of course you would start with downloading the source code
on GitHub for the version of libpqxx that
is right for you. In this explanation the libpqxx-master is the current
development version, and the release versions have names like
libpqxx-7.0.0, which is the earliest version that requires CMake to
build.
CMake is a wonderful "make" like system that runs on a large variety of operating systems. This allows a single build methodology to be used by the libpqxx developers which targets an enormous variety of operating systems and compiler options. However due to the requirements of compatibility of this large number of target systems, bugs and issues with CMake, and programming methods needed for the CMake process to be compatible with this large number of targets, some problems remain for the specific installation on Windows operating system using Visual Studio compiler.
CMake is available for several compilers for Windows, including Microsoft Visual Studio. If you are using Visual Studio, only the 2017 and later versions support the C++ 17 standard required by libpqxx 7. And libpqxx version 7 can most easily be compiled for Visual Studio using the CMake build process.
The methods here show how to install in Windows, and get past Windows install problems if they occur for you. A configurable batch file is presented which will fully automate the installation of the libpqxx library with options and features discussed in the introduction.
You can do the basic CMake build process without using the batch file and
advanced features, and understand the underlying steps, according to these
instructions. The first example will build and install only one
configuration, and can't be directly placed in a privileged location like
C:\Program Files.
In my opinion the best way to build a static libpqxx library on Windows for
Visual Studio is an "out-of-source build" using CMake, in which source and
build files are subdirectories of a top-level directory. (Check that your
version of CMake is up to date. The minimum CMake
version should be 3.17.1 and the latest is preferred. And of course a late
version of PostgreSQL
database must also be
installed, version 12 is preferred but at least version 10. Version 10 is
the last with a 32 bit Win32 installation.) In this method you put the
input source files subdirectory (libpqxx-master or libpqxx-<version>)
into the top-level directory. Then in this top-level directory execute the
following two commands (adjusting the name of the input source
accordingly):
cmake -S libpqxx-master -B build -DCMAKE_INSTALL_PREFIX="libpqxx"
This constructs a Visual Studio solution with multiple projects and CMake
build information, in the 'build' subdirectory, but does not build those
projects. The CMAKE_INSTALL_PREFIX parameter establishes the final install
directory in advance as a third subdirectory 'libpqxx', of the top level
directory. This cannot be located in the protected Program Files directory
without running CMake as administrator. Leaving off the
CMAKE_INSTALL_PREFIX parameter usually causes CMake to default to
C:\Program Files (x86)\libpqxx in the next step. This is often the wrong
install subdirectory, requires administrative privileges or will fail, and
those privileges are not granted just by logging in as admin.
Then
cmake --build build --target INSTALL
will build the projects using the native Visual Studio tools, including
copying the final installation files into the libpqxx subdirectory of your
build directory, as previously established. That libpqxx subdirectory can
be manually copied into the C:\Program Files directory if desired, to
give it a standardized location that may be expected on Windows. A manual
copy will ask for administrative rights.
That last step is actually two separate actions, and they could also be
accomplished by using the native Microsoft build tools directly within the
build that is configured in that first CMake step. That Microsoft Visual
Studio solution, called libpqxx.sln will contain projects to build the
library and to organize the generated files into an "install" directory.
That final INSTALL step exists as a project in the Visual Studio
solution, but actually just calls back to the CMake system to script the
"installation" into an organized output subdirectory. The --target INSTALL flag triggers that final INSTALL step, which depends upon the
building of the library. (Since this is a "make" system, the entire library
build is triggered by this one command, followed by the install process.)
A version of PostgreSQL must be installed on the build computer, at least the libraries must be installed, in order to build the libpqxx library. See the notes on additional flags below if the first CMake command cannot locate the correct PostgreSQL library automatically.
One way to automate this build process is to copy the following lines and
paste into a good programming editor, which will fix any Windows new line
problems. Then save as build.bat batch script file, into your top-level
directory. Click on the batch file to automate the build process:
REM Automated build of libpqxx placing install files in libpqxx subdirectory.
cmake -S libpqxx-master -B build -DCMAKE_INSTALL_PREFIX="libpqxx"
if %errorlevel%==0 cmake --build build --target INSTALL
pauseAny changes can be made by clicking the batch build file again and only
necessary changes will be compiled, as is normal for a "make" process. Once
again, use libpqxx-master for the most recent build of libpqxx, or change
that to match the libpqxx-<version> number you are using, here and in the
examples that follow.
Flags that can be added on the first cmake line include: -A x64 or -A Win32 These will select the target architecture as 64 or 32 bit. -G "Visual Studio 15 2017" may be used to select the 2017 version of Visual
Studio, or explicitly select -G "Visual Studio 16 2019" (default if
installed). The architecture and generator parameter values must be exactly
as shown. Use
-DPostgreSQL_ROOT="C:\Program Files\PostgreSQL\12"
to select the version of PostgreSQL at the specified location. To compile
for Win32, the "C:\Program Files (x86)\PostgreSQL\10" version of libpq
will probably be required from the x86 directory (and include -A Win32).
These flags can also be added to the first cmake line in the example
below.
Some additional flags that can be used on the first cmake command line,
as noted in libpqxx's BUILDING-cmake.md document: -DSKIP_BUILD_TEST=on
skips compiling libpqxx's tests. -DBUILD_SHARED_LIBS=on to build a shared
library, a DLL version of libpqxx library. -DBUILD_SHARED_LIBS=off to
build a static library. -DBUILD_DOC=on to use Doxygen to build the
documentation (not related to whether documentation is present in the
installation). (None of this last set of flags have been implemented in the
current version of the Easy-PQXX batch file presented below, by the way.)
The second (build) cmake command can also have: --config Release to
switch the install from a Debug to a Release configuration.
The build cmake line can also have, at the very end, -- /property:CharacterSet=Unicode to change the character set from MultiByte
to Unicode. That flag (including the -- separated by spaces at the end
before the added flag) can also be applied in the 2nd and 3rd cmake build
lines in the example below to change the character set, and the added flag
is passed directly to the native compiler tool without cmake interpreting
it.
A slightly more complex sequence of commands will build (completely separate) Debug and Release installations:
REM Automated build of libpqxx, both Debug and Release
cmake -S libpqxx-master -B build
if %errorlevel%==0 cmake --build build --config Debug
if %errorlevel%==0 cmake --build build --config Release
if %errorlevel%==0 cmake --install build --config Debug --prefix "libpqxx/Debug"
if %errorlevel%==0 cmake --install build --config Release --prefix "libpqxx/Release"
pauseSee the notes above for added flags that can be used in this example as
well. (Note most flags listed above go on the first cmake line, but the
character set flags go at the end of the two --build lines.)
If you copy the basic_libpqxx.props property sheet from this repository
to the libpqxx subdirectory created above, and edit line 17 to correct
the location of the PostgreSQL library if necessary, then you can include
that property sheet in your new applications. This means you don't have to
manually enter the required lists of libraries and their locations into
your programs to use the new library. Just use the Property Manager tab in
Visual Studio, and right click on project to select Add Existing Property Sheet... to incorporate that. You should not have errors in include files
or libraries in your new application regarding libpqxx.
If you want to automatically copy the required DLLs from PostgreSQL into
your executable directory in your new project, then also add the
basic_DLL.props property sheet to your project configurations. That
property page should be saved in the libpqxx subdirectory also, and next to
that file add a bin subdirectory into which you copy needed DLL files
from PostgreSQL as you discover them.
Each time you run your application it will probably ask for a DLL file,
until you fill out the entire set needed and build them into the executable
directory. For version 12 PostgreSQL, x64, the following list of DLL files
was needed: libpq.dll libcrypto-1_1-x64.dll libiconv-2.dll
libintl-8.dll libssl-1_1-x64.dll. For version 10, Win32, the files are
libpq.dll libcrypto-1_1.dll libiconv-2.dll libintl-8.dll
libssl-1_1.dll.
If you want the final installation of libpqxx in the C:\Program Files\libpqxx directory, you could just copy and paste the libpqxx
subdirectory created above into your Program Files directory--and Windows
will ask for permissions.
A couple of compiling configuration flags that CMake does not set in Windows, even though the features are available, are as follows:
#define PQXX_HAVE_CHARCONV_FLOAT
#define PQXX_HAVE_CHARCONV_INTIn your build\include\pqxx directory, are three files:
config-internal-compiler.h
config-internal-libpq.h
config-public-compiler.h
Adding those definitions at the end of each of those three files will enable efficiency features in libpqxx. As of version 7.1.2 "master" in development on June 15, 2020, some changes are needed before these efficiency modifications will work. But after those fixes are made so the library compiles for Visual Studio, those definitions can be added.
To make those changes, edit the files after the very first CMake step which
constructs the Visual Studio solution files in your build directory.
The batch file Easy-PQXX.bat supplied here does basically the same thing
as the last example above, building libpqxx with both Release and Debug
libraries, but also creates appropriate property sheet for use of the
library, installs the libraries and DLLs in a standardized location
(usually C:\Program Files\libpqxx), and automatically asks for admin
privileges. Optionally the patches needed to implement efficiency changes
can be applied between constructing the solution and the compiling it. It
places the library in a named subdirectory of libpqxx install, so that
variously configured installs have different names. Furthermore it
organizes the installation as a single directory with include and 'share'
directories (with documentation), but the lib directory has both a Debug
and Release subdirectory with the respective library. (The simplified
example above wound up with two copies of the include and the documentation
directories.)
Three other batch files are provided in this repository:
Easy-PQXX-patch.bat is pre-configured to patch the CMake generated files
with efficiency modifications, consistent with the latest development copy
of libpqxx-master. Easy-PQXX-x64Unicode.bat is pre-configured for Unicode
character set as well as the efficiency modifications in a 64 bit
compilation. (Useful along with wxWidgets library.) Easy-PQXX-Win32.bat
is pre-configured for Win32 (x86) compiling. The latter has the typical 32
bit PostgreSQL location selected.
In all cases the user may have to make some configuration changes to adapt
the use. The Easy-PQXX.bat is always the master copy, and the others are
derived by copying and changing one or more of the settings. If there is
ever a disparity, Easy-PQXX.bat is the maintained master copy.
This batch file has a top section to allow the user to configure the build.
As noted in the batch file, it should be copied to the top level directory
used to build the libpqxx system, using your favorite programming text
editor. Since presumably you are using Visual Studio 2017 or later for
the compile (you wouldn't be here otherwise), Visual Studio can be used for
that purpose, and check that you have the menu Edit--Advanced--End of Line Sequence set to CRLF when you save. (Hopefully any code-page issues would
be resolved in this step as well.) Set the configuration variables (top
section) to the values you want, then save the edited batch file in that
top level directory for the install.
Please do not change the operations sections of this batch file! This
batch file can recursively run itself as administrator for the last
installation step (which just uses xcopy to place files), but that gives
the batch file privileges to do almost anything. Making changes if you do
not completely understand them can have unexpected results.
Please do change the configuration variables in the top section to match your requirements. Each variable has an explanation.
To activate the batch file (in the top-level subdirectory for the project) just click (or double click) the file. It will open in a command window, and has a pause at the end so you can read the results. After build it may ask permissions to run in administrative mode to do the final copy to the Program Files directory. After giving permission, a yellow background command window is doing the final copy. Then hit a key to end each window, after checking for proper operation.
This batch file first configures the build, applies patches to the configuration if specified, compiles the libraries (both Release and Debug as selected), but in separate local pre-installation work directories. The CMake methods are only configured to do this as separate file groupings.
Then the batch file copies the separate installations into a singe coherent directory with just one include subdirectory, just one 'share' subdirectory with documentation, and with a lib directory that is subdivided by Debug and Release folders. Another subdirectory, 'bin' is added to contain the external PostgreSQL libraries and DLL files required for applications using the libpqxx library. Property page files are also provided, which can be used in Visual Studio projects to easily reference the libraries and DLL files needed.
Create your new project in Visual Studio. (Often a completely new project will be required, because the changes are significant from previous versions if you are upgrading old work. For example you don't need to provide locations for libraries and include files any more!)
The first setting that is required is to change your C++ Language Standard to ISO C++ 17. (We can't do that from Property Sheets.)
Then in the "Property Manager" tab, select each of your Debug and Release versions (in sequence). Right click and "Add Existing Property Sheet". Unfortunately VS seems to forget where you were, so you have to click around to the install directory each time. Find the appropriately named subdirectory of the libpqxx install directory, for the respective build library to be used. At the base of that directory are three property sheets (.props) named libpqxx, libpqxx_ALL, and libpqxx_DLL. The first is just the library (no DLL). The _DLL version just copies the DLL's to your executable directory as a post-build event. And the _ALL version does it all. Select the libpqxx_ALL.props sheet. (You need to do this for both the Debug and the Release configurations, but use the same property sheet for both.)
Then compile your application! (Thats all.)
You can switch your application between Debug and Release configurations and the correctly built library is chosen automatically.
(If you are building both x64 and Win32 versions of your application, you will have to configure a 2nd copy of the batch file for Win32, and the output libraries will appear in a separate subdirectory of the libpqxx installation. When adding property sheets, add the sheets from the appropriate subdirectory in the respective configuration from the Property Manager.)
Note that the installation directory looks like this:
bin
include
lib
libpqxx.props
libpqxx_ALL.props
libpqxx_DLL.props
share
The lib subdirectory is different from the normal libpqxx make, since it contains separate Debug and Release subdirectories, each with a library. The libpqxx_ALL.props property page causes the application to refer to the library, the include files, and also copy the DLLs for PostgreSQL to the execute directory. The libpqxx.props refers to the library, the include files, but does not copy the DLLs. The libpqxx_DLL.props property page only copies the DLLs. (This last can be used in the test suite generated in the CMake build to get it going quickly.)
In the configured Visual Studio solution is a test suite with project name "runner". To run this test suite to test the build, some steps need to be done in this Windows version. Note that the build inserts references to the local copies of the library and references the insert files path from the build source and build directories. However the executable may not have available the DLL files from PostgreSQL.
Those DLLs could be made available by putting the bin directory of the
PostgreSQL installation of the Program Files directory into the path for
the local user. (This has an advantage of providing access to the psql
utility, for example, in any open command window without special
environment settings.) However this may also become troublesome if you have
both 64 and 32 bit versions of PostgreSQL installed, for example.
Another way to provide those DLLs with little effort is to use the property page for the respective compile to load the DLLs with the runner application. Open the libpqxx.sln solution in the build subdirectory with the Visual Studio IDE. The DLL only property page will be used. However we are lucky that there is only one architecture specified in the libpqxx projects, so one property page insertion can apply to all the sub-configurations. In the Property Manager tab, look for the 'runner' application. Right click on that (as a whole, not its individual configurations) and right click and pick Add Existing Property Sheet. You could use the libpqxx_DLL.props property sheet from the final installation, but I just choose the local install subdirectory matching the installation type, since it is in a fixed relative position to the library build, like the other files used in this test project.
Then you need to find or create a PostgreSQL database for the testing application play in. To connect that, set the environment variables, here shown on the local PostgreSQL server. Of course use the appropriate values for these variables, especially the name of the testing database you have chosen, and appropriate user.
PGHOST=localhost
PGPORT=5432
PGDATABASE=testing
PGUSER=postgres
To do this, find the project properties debugging environment configuration.
You may have to add PGPASSWORD= setting to the list if you don't have a
pgpass.conf file configured for applications (like .pgpass on Linux). (See
https://www.postgresql.org/docs/current/libpq-pgpass.html for pgpass file
configuration.) But be forewarned placing the password in your program is
probably a security risk, the pgpass file is probably better.
With only the Property Page for the DLL include added to the runner application, and the environment variables supplied above, the runner test suite should run correctly by starting from the Visual Studio IDE.