
Welcome to libpqxx, a C++ API to the PostgreSQL database management system.
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 Windows systems.

The only Windows compilers currently described in this document 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.
1) If you're using Visual C++, run VCVARS32.BAT to prepare the environment.
2) Edit win32/common (if you're using Visaul C++) or win32/MinGW.mak (if you're
   using MinGW) to reflect the correct paths to your PostgreSQL includes
   and library files etc.
3) Create the configuration headers include/pqxx/config-*-*.h.  These are
   normally generated by the configure script, but this file documents the
   procedure for systems unable to run this script.  How these files work is
   described below.
4) Modify the "common" makefile to suit your environment.  See "Changing the
   makefile" below.
5) Now "nmake /f libpqxx.mak ALL" will compile all dynamic, static, debug and 
   release libraries. You will find them in the win32\lib directory.
   
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 run the entire regression test.  For Visual C++ users, the following steps
should accomplish the same:

6) "nmake /f test.mak ALL" will compile and link all the test files. It is
   currently set to use the dll version of libpqxx.
7) 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 passing a connection string.
8) 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.
 

Getting Started with MinGW 
(contributed by Michael J. Pedersen, 2004-08-17)

Well, here's the very brief overview of using it:

First, the downloads:
1) MinGW (http://www.mingw.org/), plus any updates. It is recommended to get all
   of them.
2) MSYS (http://www.mingw.org/), again with any updates. Same recommendation.
3) PostgreSQL (http://www.postgresql.org). Recommended version is 8.0.0beta,
   since it builds the easiest on Windows.
4) libpqxx (http://pqxx.tk). Recommended version is no less than 2.2.9.
   2.2.7, while it can be made to work, does not compile as cleanly under
   MinGW/MSYS as does 2.2.9 (specifically, pqxxbench produces failures that were
   not found when following these steps under 2.2.9)
5) zlib (http://www.zlib.org/). Recommended to get latest version.

Next, the steps to compile/install
1) Install MinGW (install to c:\mingw)
2) Install MSyS into MinGW structure (c:\mingw)
3) Run MSYS (Start->Programs->MinGW->MSYS->msys)
4) extract, compile, and install zlib
    ./configure --prefix=c:/mingw/local && make && make install
5) Extract and compile postgresql
        ./configure --prefix=c:/mingw/local --with-includes=c:/mingw/local/include --with-libs=c:/mingw/local/lib
        ln -s src/backend/port/tas/dummy.s src/backend/port/tas.s
        ln -s src/backend/port/dynloader/win32.c src/backend/port/dynloader.c
        make && make install
6) Copy psql.exe and libpq.dll to somewhere on your path
7) ln -s /mingw/bin/mingw32-make.exe /mingw/bin/make.exe
8) extract and compile libpqxx
        export LDFLAGS=-lws2_32
        ./configure --prefix=c:/mingw/local --disable-shared --enable-static
        make && make install

Finally, when compiling your own programs, use the following steps
(examples only here)

g++ -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.

Note that 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
typical compiler shortcomings, functions missing in older libpq versions, etc.

Each of these items is 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
(regardless of value; 0 will work as well as 1, but a value of 1 is the
convention) or disabled if the macro is left undefined.  Some few items require
a meaningful value, e.g. PGSTD needs to be defined to the name of the standard
namespace (typically std).

At the time of writing, there are 4 of these configuration headers that you
need to concern yourself about, all located in the include/pqxx subdirectory:

	config-internal-compiler.h
	config-internal-libpq.h
	config-public-compiler.h
	config-public-libpq.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; 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.

Sample versions of these headers, for various compilers and libpq versions, can
be found in the config/sample-headers/ directory.  Try copying the four 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 makefile

There are 2 items in the makefile that may need to be changed, all have at
least a little bit of documentation.  All these changes take place in the
file "common" 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 the release version of libpq is located.  Refer to the postgres
documentation on building this file if you don't have one.


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 located 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 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.

CAUTION: DO NOT try to unset yes/no configuration items by defining their macros
to zero.  A value of zero is counted as "yes."  If it's defined, it means "yes"
regardless of what actual value you set.

