Welcome to libpqxx, a C++ API to the PostgreSQL database management system.

This file documents building and installation of libpqxx on Windows systems.
Please see the regular README for general instructions on building, installing,
and using the library.  If you are using Cygwin, MSYS, or another Unix-like
environment please try the Unix configuration & build procedure instead of the
one described here.

Things are a bit more complicated for plain Windows systems, although some help
for getting started in an MSYS environment is given below.  The only Windows
compilers currently described here are:

	Visual C++ (7.0 or above)
	MinGW

If you are using a different compiler, such as Borland C++ Builder, you should
still be able to get it to work.  If you do, or if you fail, please report your
results so any problems can be resolved and support for the compiler can be
included in the standard libpqxx distribution.

To get started quickly on a Windows system, use the command line.

Before you can build libpqxx, make sure you have a working installation of
libpq, the C-level client library included with PostgreSQL.  Note that for some
reason, enabling the "Include and Library Files" in the graphical PostgreSQL
installer may not be enough to ensure this.

If you have compiled PostgreSQL from source, its directory tree should contain
libpq in binary form, as well as its headers.  Look for these in
src/interfaces/libpq: Visual C++ will generate separate Debug and Release
versions in subdirectories called Debug and Release, respectively, in that
location.

If you have not compiled PostgreSQL itself, you can do so by downloading its
source code from http://postgresql.org/, unpacking it, and from the command line
going in to its source directory and typing:

	nmake /f win32.mak

The rest of this text will assume that you have the libpq library in its binary 
form(s) and its header files.  Now, to work on building libpqxx!

The first thing to do before you can build libpqxx is to provide certain common
settings.

 i) Copy win32/common-sample to win32/common, and edit the latter to reflect the
   paths to your PostgreSQL includes and library files.  On Windows these may
   differ from one person's system to another, but if you compiled PostgreSQL
   for yourself to obtain libpq, simply set the PGSQLSRC in win32/common to
   point to your PostgreSQL directory tree.

ii) Create the configuration headers include/pqxx/config-*-*.h.  From
   config/sample-headers, copy the ones from the directories most accurately
   describing your compiler and libpq version, respectively.  On a Unix-like
   system these would be generated by the configure script; in the Windows case
   they may need some editing.  How these files work is described in more detail
   below.

The rest of the procedure depends on your compiler.

If you're using Visual C++:
1) Run VCVARS32.BAT to prepare the environment.  Then CD into the main directory
   of the libpqxx source tree.  Among other things it will contain the files 
   "configure" and "Makefile.am," and subdirectories "src," "include," "win32"
   etc.
2) Run "nmake /f win32/vc-libpqxx.mak ALL" will compile all dynamic, static,
   debug and release libraries.  Once completed, you will find them in the
   win32/lib directory.

If you're using MinGW (but without a Unix-like environment, see above):
1) Run "make -f win32/MinGW.mak"
2) Consider installing a Unix-like environment like MSYS to automate all this!
   
After that, it is recommended that you compile and run the self-test programs
included in the package.  Unix, Cygwin, or MSYS users simply type "make check"
to build and run the entire regression test.  For Visual C++ users, the
following steps should accomplish the same:

 3) "nmake /f vc-test.mak ALL" will compile and link all the test files. It is
    currently set to use the DLL version of libpqxx.
 4) Make sure a PostgreSQL database is running and accessible; set up the
    environment as described in README so that the test programs can access the
    database without needing to pass a connection string.
 5) Run each of the test programs in order.  Some of them will generate lots of
    output, some won't produce any.  Error messages that are expected in the
    course of a normal test run are prefixed with "(Expected)" to show that they
    are not harmful.  All tests should complete successfully.

Here's how to set up a Visual C++ project file for your own program using
libpqxx (based on description by Alexandre Hanft, 2006-03-06):

 6) Create a new project in the Visual C++ development environment.
 7) Add your first C++ file and provide some initial code, e.g. by copying the
    test/test001.cxx source file from the libpqxx source tree.
 8) Edit Project Properties, C++: Additional Include Directories.  Add the
    location of the "include" directory found in your libpqxx source tree, e.g.
    C:\src\libpqxx\include if you keep libpqxx in C:\src\libpqxx.
 9) Edit Project Properties, Linker: Additional Library Directories.  Add the
    directories where your libpq and libpqxx libraries are, for example:
    C:\src\postgresql-8.1.3\interfaces\libpq\Release;C:\src\libpqxx\win32\lib
    That is for your Release build.  Do the same for your Debug build, but
    replace that "Release" in there with "Debug" there.
10) Edit Project Properties, Linker: Additional Dependencies.  Add:
    libpqxx.lib.
11) Your program should build successfully now.  It may not be ready to run yet,
    because some dynamically loaded libraries are needed when starting your
    program.  Copy comerr32.dll and krb5_32.dll from the "bin" directory in your
    PostgreSQL directory tree, and the libpqxx DLLs from win32/lib in your
    libpqxx tree, directly into your project's directory so the system can find
    them when your development environment launches your program.
12) Your program should now be able to run.  However, you may need to tell it
    how to connect to a database.  If you set the environment variables
    PGDATABASE, PGHOST, PGPORT, and PGUSER as described in the libpqxx README
    file, your program should be able to connect without passing further
    parameters.  Sensible defaults are provided for all of these variables; if
    you have a database running on your local machine, with the same name as
    your username, and you are allowed to log into that without password (this
    is the default on some systems), then no settings should be needed.
13) Once your program gets to the point where users should be able to configure
    it properly, change them to pass a connection string where it connects to
    any databases, and include your user's configuration settings.  A typical
    connection string setting all parameters named above might look like:
    	"dbname=testbase user=testuser host=my.dbserver.somewhere.com"
14) For any other problems, please check the project homepage as listed in the
    main libpqxx README file.


Getting Started with MinGW and MSYS
(based on contribution by Michael J. Pedersen, 2004-08-17)

MSYS is a Unix-like environment for Windows.  Once you have this installed,
building libpqxx should be a lot more like it is under Unix except that the
locations of libraries and such aren't sufficiently standardized.

Packages to download if you don't have them already:
1) MinGW (http://www.mingw.org/), plus any updates.
2) MSYS (http://www.mingw.org/), again with any updates.
3) w32api (http://www.mingw.org/).
4) PostgreSQL (http://www.postgresql.org/).
5) zlib (http://www.zlib.org/).

It is generally recommended to get the latest versions of these packages.

Compiling and installing PostgreSQL before you get to libpqxx:
1) Install MinGW (install to c:\mingw)
2) Install MSYS--but not into MinGW directory tree!
3) Run MSYS (Start->Programs->MinGW->MSYS->msys)
4) Extract, compile, and install zlib
    # From main source directory of zlib:
    ./configure --prefix=c:/mingw/local && make && make install
5) Extract, compile, and install postgres
    # From main source directory of PostgreSQL:
    ./configure --prefix=c:/mingw/local --with-includes=c:/mingw/local/include --with-libs=c:/mingw/local/lib
    make && make install
6) Extract, compile, and install libpqxx
    export LDFLAGS=-lws2_32
    ./configure --prefix=c:/mingw/local --enable-static
    make && make install

If you don't have and don't want to install MSYS, you won't be able to perform
the "./configure" step.  You can build libpqxx without it, but it takes a bit
more work and doesn't build the self-test.  Use the special makefile MinGW.mak
in the win32 directory instead of the regular Makefile, and follow the procedure
described below to use the prefabricated configuration headers enclosed in the
source archive.

Building libpqxx without MSYS:

	# (first set up configuration headers, see below)
	export LDFLAGS=-lws2_32
	make -f win32/MinGW.mak
	# (install library, headers and pqxx-config manually on your system)

Having installed libpqxx, when compiling your own programs, use the following
steps (examples only here):

g++ -c -o myfile.o myfile.cpp `pqxx-config --cflags`
g++ -o myexec myfile.o `pqxx-config --libs` -lws2_32

Note that the linker step (g++ -o myexec) will give a spurious warning
about not knowing how to use the -R flag, but the executable will still
be generated, and work just fine.

The last argument to that linker step MUST be -lws2_32.  Without it, the link
will provide errors about undefined references to select(). If it's not the last
argument, you will get the same results.  Make sure it's there, and make sure
it's last. Trust me, you'll be happier.


Setting up the configuration headers

Several headers, normally generated by the configure script, define certain
aspects of your compilation environment so that the library can work around
compiler shortcomings, functions missing in older libpq versions, etc.  (Samples
for various compiler and libpq versions can be found in the subdirectory
config/sample-headers, so look there first.)

Each of the aspects mentioned below is represented by a configuration item--a
preprocessor macro that is either #define'd to some value or not defined at all.
Most of the items are of a Boolean nature, i.e.  some feature or workaround is
enabled if the corresponding macro is defined or disabled if the macro is left
undefined.  Note that defining any of these macros to 0 means "true," just like
defining it to 1 or anything else does.  The value 1 is more for convention than
anything else.

Some other items require a meaningful value however, e.g. PGSTD needs to be
defined to the name of the standard namespace (typically std).

At the time of writing, there are 3 of these configuration headers that you
need to concern yourself about, all of which should be created in the
include/pqxx subdirectory:

	config-internal-compiler.h
	config-internal-libpq.h
	config-public-compiler.h


The names contain two variables:

1. Internal or public.  Configuration items that affect the compilation of
your client program are located in the config-public-*.h files (currently only
one file); ones that affect only the compilation of the library itself are kept
in the config-internal-*.h ones and are not included at all when compiling
client programs.  Public configuration items (except PGSTD) are prefixed with
PQXX_ to avoid clashes with macros defined by other code.

2. Autotools-related, compiler-related, or libpq-related.  The autotools items
are of no real interest, but the compiler and libpq ones are different.  The
compiler-related ones describe features and shortcomings of the compiler
environment, such as the availability of the <unistd.h> header or the ability
to compile certain complex C++ language constructs.  The libpq items describe
what features are available in the version of libpq you're compiling against.
At the time of writing, the latter all take the HAVE_... form; defining such a
macro indicates that the corresponding feature is available.

A complete list of configuration items and their categorizations can be found in
the configitems file.  The normal configure script reads the list of items from
include/pqxx/config.h.in and writes them to include/pqxx/config.h, then splits
them up into the five smaller files as directed by the configitems database.

Again, sample versions of these headers for various compilers and libpq versions
can be found in the config/sample-headers/ directory.  Try copying the three
headers for the compiler and libpq version most resembling your own environment
to include/pqxx/ and, if you have any problems compiling with those, editing
them by hand to enable or disable features that appear to be giving you trouble.


Changing the Visual C++ makefile

There are 2 items in this makefile that may need to be changed, all have at
least a little bit of documentation.  All these changes take place in the
separate file "common", which is shared between the regular makefile and the
makefile for the regression test, so you shouldn't get any oddities when
compiling the test cases due to a mismatch in compiler settings.

PGSQLSRC
You will need to change this option.  While we don't actually use the source
files from postgres, some of the header files are necessary.  Set this option
where the src directory of postgres is located.  It can handle it from there.

LIBPATH
This is where libpq is located.  Refer to the postgres documentation on building
that library if you don't have one.

Make sure your LIBPATH includes at least the version of libpq that corresponds
to the mode you want to build libpqxx in: if you want to produce a debug build
of libpqxx, ensure that at least the debug build of libpq is in this path.  If
you intend to produce a release build, ensure that the release build of libpq is
available somewhere in your LIBPATH directories.  The given example provides for
both of these.


Shared and Static Libraries, or DLL vs. .LIB

There are two ways to build the libpqxx library: as a shared library (known
in the Unix world as a Shared Object or "so," but in the Windows world as a
Dynamically Loaded Library or DLL) or as a static library (whose name would
end in ".a" on Unix systems but in ".LIB" on Windows systems).  Linking your
own applications to these types of libraries is quite similar, except with a
DLL the system will also have to be able to find the library when your program
is loaded--not just when you are compiling it.

Unlike the situation in the Unix world, however, your choice on this point must
be known as you compile your application code.  With libpqxx you do this by
defining the preprocessor macro PQXX_SHARED when compiling your code for use
with a libpqxx DLL.  Leave this definition out if you intend to link to the
static version of the library.

(Internally, the library will also set this variable according to which kind of
library it is building.  It has a slightly different meaning in this case, but
unless you are helping debug the library you need not concern yourself with
this distinction.)


Troubleshooting

The biggest typical problem for Windows/VC++ users is the need to edit the
configuration headers manually, resulting usually in compile errors, e.g. for
missing header files.  Thus, if you get a compile error, the first places to
look are the config-*-*.h and config-*-*.h files in include/pqxx.

If, for instance, the error states that the header file <sys/select.h> is
missing, you will find a configuration variable called PQXX_HAVE_SYS_SELECT_H,
which should not be set if your system doesn't have sys/select.h.  Remove the
line defining this variable from the configuration header where it is defined
(see the configitems file for a list of locations) and the error should
disappear on the next compilation attempt.

If you have to edit your configuration headers, please send your results to the
author or to the libpqxx-general mailing list so that headers corresponding to
your environment can be included in later libpqxx releases.  Be sure to give a
usable personal name so you can be properly credited in the changelog!

CAUTION: DO NOT try to unset yes/no configuration items by defining their macros
to zero.  A value of zero counts as "yes."  If a macro is defined at all, that
means "yes" (or "true," or "enabled" etc.) regardless of what actual value you
set.  To disable an item, make sure it is not defined at all.

