INSTALL

Compiling and installing psycopg
********************************

** Important note: if you plan to use psycopg2 in a multithreaded application,
   make sure that your libpq has been compiled with the --with-thread-safety
   option. psycopg2 will work correctly even with a non-thread-safe libpq but
   libpq will leak memory.

psycopg2 uses distutils for its build process, so most of the process is
executed by the setup.py script.  Before building psycopg look at
setup.cfg file and change any settings to follow your system (or taste);
then:

    python setup.py build

to build in the local directory; and:

    python setup.py install

to install system-wide.


Common errors and build problems
================================

One of the most common errors is trying to build psycopg without the right
development headers for PostgreSQL, Python or both. If you get errors, look
for the following messages and then take the appropriate action:

libpq-fe.h: No such file or directory
  PostgreSQL headers are not properly installed on your system or are
  installed in a non default path. First make sure they are installed, then
  check setup.cfg and make sure pg_config points to a valid pg_config
  executable. If you don't have a working pg_config try to play with the
  include_dirs variable (and note that a working pg_config is better.)


Running the test suite
======================

The included Makefile allows to run all the tests included in the
distribution. Just use:

    make
    make check

The tests are run against a database called psycopg2_test on unix socket
and standard port. You can configure a different database to run the test
by setting the environment variables:

- PSYCOPG2_TESTDB
- PSYCOPG2_TESTDB_HOST
- PSYCOPG2_TESTDB_PORT
- PSYCOPG2_TESTDB_USER

The database should be created before running the tests.

The standard Python unittest is used to run the tests. But if unittest2 is
found it will be used instead, with the result of having more informations
about skipped tests.


Building the documentation
==========================

In order to build the documentation included in the distribution, use

    make env
    make docs

The first command will install all the dependencies (Sphinx, Docutils) in
an 'env' directory in the project tree. The second command will build both
the html format (in the 'doc/html' directory) and in plain text
(doc/psycopg2.txt)


Using setuptools and EasyInstall
================================

If setuptools are installed on your system you can easily create an egg for
psycopg and install it. Download the source distribution (if you're reading
this file you probably already have) and then edit setup.cfg to your taste
and build from the source distribution top-level directory using:

    easy_install .


Compiling under Windows with mingw32
====================================

You can compile psycopg under Windows platform with mingw32
(http://www.mingw.org/) compiler. MinGW is also shipped with IDEs such as
Dev-C++ (http://www.bloodshed.net/devcpp.html) and Code::Blocks
(http://www.codeblocks.org). gcc binaries should be in your PATH.

You need a PostgreSQL with include and libary files installed. At least v8.0
is required.

First you need to create a libpython2X.a as described in
http://starship.python.net/crew/kernr/mingw32/Notes.html. Then run:

    python setup.py build_ext --compiler=mingw32 install