source: trunk/docs/install.txt @ 344

Last change on this file since 344 was 344, checked in by cito, 11 years ago

Mention the new requirements (Python 2.3 and PostgreSQL 7.4).

File size: 7.0 KB
Line 
1=====================
2PyGreSQL Installation
3=====================
4
5.. sectnum::
6.. contents:: Contents
7
8
9General
10=======
11
12You must first have installed Python and PostgreSQL on your system.
13If you want to access remote database only, you don't need to install
14the full PostgreSQL server, but only the C interface (libpq). If you
15are on Windows, make sure that the directory with libpq.dll is in your
16``PATH`` environment variable.
17
18The current version of PyGreSQL has been tested with Python 2.5 and
19PostGreSQL 8.3. Older version should work as well, but you will need
20at least Python 2.3 and PostgreSQL 7.4.
21
22If you are using the DB-API 2.0 module you may consider installing
23`mxDateTime <http://www.egenix.com/files/python/mxDateTime.html>`_.
24Otherwise, the Python standard lib datetime module is used.
25
26PyGreSQL will be installed as three modules, a dynamic module called
27_pg.pyd, and two pure Python wrapper modules called pg.py and pgdb.py.
28All three files will be installed directly into the Python site-packages
29directory. To uninstall PyGreSQL, simply remove these three files again.
30
31
32Installing from a Binary Distribution
33=====================================
34
35This is the easiest way to install PyGreSQL.
36
37You can currently download PyGreSQL as Linux RPM, NetBSD package and Windows
38installer. Make sure the required Python version of the binary package matches
39the Python version you have installed.
40
41Install the package as usual on your system.
42
43Note that the documentation is currently only included in the source package.
44
45
46Installing from Source
47======================
48
49If you want to install PyGreSQL from Source, or there is no binary
50package available for your platform, follow these instructions.
51
52Make sure the Python header files and PostgreSQL client and server header
53files are installed. These come usually with the "devel" packages on Unix
54systems and the installer executables on Windows systems.
55
56If you are using a precompiled PostgreSQL, you will also need the pg_config
57tool. This is usually also part of the "devel" package on Unix, and will be
58installed as part of the database server feature on Windows systems.
59
60Building and installing with Distutils
61--------------------------------------
62
63You can build and install PyGreSQL using Distutils.
64
65On a Microsoft Windows system, you should have the Microsoft Visual C++ compiler
66and the Microsoft .NET Framework SDK installed and on your search path.
67If you want to use the free Microsoft Visual C++ Toolkit 2003 compiler,
68you need to `patch distutils <http://www.vrplumber.com/programming/mstoolkit/>`_.
69Alternatively, you can use `MinGW <http://www.mingw.org>`_.
70
71Download and unpack the PyGreSQL source tarball if you haven't already done so.
72
73Type the following commands to build and install PyGreSQL::
74
75    python setup.py build
76    python setup.py install
77
78Note that the official Python 2.4 distribution for Microsoft Windows is now
79using msvcr71 instead of msvcrt as its common runtime library. So, if you are
80using MinGW to build PyGreSQL for Python 2.4 on a Windows system, you should
81edit the file ``%MinGWpath%/lib/gcc/%MinGWversion%/specs`` and change the entry
82that reads ``-lmsvcrt`` to ``-lmsvcr71``. Then use the following command to
83build and install PyGreSQL::
84
85    python setup.py build -c mingw32 install
86
87Now you should be ready to use PyGreSQL.
88
89Compiling Manually
90------------------
91
92The source file for compiling the dynamic module is called pgmodule.c.
93You have two options. You can compile PyGreSQL as a stand-alone module
94or you can build it into the Python interpreter.
95
96Stand-Alone
97-----------
98
99* In the directory containing ``pgmodule.c``, run the following command::
100
101    cc -fpic -shared -o _pg.so -I$PYINC -I$PGINC -I$PSINC -L$PGLIB -lpq pgmodule.c
102
103  where you have to set::
104
105    PYINC = path to the Python include files
106            (usually something like /usr/include/python)
107    PGINC = path to the PostgreSQL client include files
108            (something like /usr/include/pgsql or /usr/include/postgresql)
109    PSINC = path to the PostgreSQL server include files
110            (like /usr/include/pgsql/server or /usr/include/postgresql/server)
111    PGLIB = path to the PostgreSQL object code libraries (usually /usr/lib)
112
113  If you are not sure about the above paths, try something like::
114
115    PYINC=`find /usr -name Python.h`
116    PGINC=`find /usr -name libpq-fe.h`
117    PSINC=`find /usr -name postgres.h`
118    PGLIB=`find /usr -name libpq.so`
119
120  If you have the ``pg_config`` tool installed, you can set::
121
122    PGINC=`pg_config --includedir`
123    PSINC=`pg_config --includedir-server`
124    PGLIB=`pg_config --libdir`
125
126  Some options may be added to this line::
127
128    -DNO_DEF_VAR   no default variables support
129    -DNO_DIRECT    no direct access methods
130    -DNO_LARGE     no large object support
131    -DNO_PQSOCKET  if running an older PostgreSQL
132
133  Define ``NO_PQSOCKET`` if you are using a version of PostgreSQL before 6.4
134  that does not have the PQsocket function. The other options will be
135  described in the next sections.
136
137  On some systems you may need to include ``-lcrypt`` in the list of libraries
138  to make it compile.
139
140* Test the new module. Something like the following should work::
141
142    $ python
143
144    >>> import _pg
145    >>> db = _pg.connect('thilo','localhost')
146    >>> db.query("INSERT INTO test VALUES ('ping','pong')")
147    18304
148    >>> db.query("SELECT * FROM test")
149    eins|zwei
150    ----+----
151    ping|pong
152    (1 row)
153
154* Finally, move the ``_pg.so``, ``pg.py``, and ``pgdb.py`` to a directory in
155  your ``PYTHONPATH``. A good place would be ``/usr/lib/python/site-packages``
156  if your Python modules are in ``/usr/lib/python``.
157
158Built-in to Python interpreter
159------------------------------
160
161* Find the directory where your ``Setup`` file lives (usually in the ``Modules``
162  subdirectory) in the Python source hierarchy and copy or symlink the
163  ``pgmodule.c`` file there.
164
165* Add the following line to your 'Setup' file::
166
167    _pg  pgmodule.c -I$PGINC -I$PSINC -L$PGLIB -lpq
168
169  where::
170
171    PGINC = path to the PostgreSQL client include files (see above)
172    PSINC = path to the PostgreSQL server include files (see above)
173    PGLIB = path to the PostgreSQL object code libraries (see above)
174
175  Some options may be added to this line::
176
177    -DNO_DEF_VAR   no default variables support
178    -DNO_DIRECT    no direct access methods
179    -DNO_LARGE     no large object support
180    -DNO_PQSOCKET  if running an older PostgreSQL (see above)
181
182  On some systems you may need to include ``-lcrypt`` in the list of libraries
183  to make it compile.
184
185* If you want a shared module, make sure that the ``shared`` keyword is
186  uncommented and add the above line below it. You used to need to install
187  your shared modules with ``make sharedinstall`` but this no longer seems
188  to be true.
189
190* Copy ``pg.py`` to the lib directory where the rest of your modules are.
191  For example, that's ``/usr/local/lib/Python`` on my system.
192
193* Rebuild Python from the root directory of the Python source hierarchy by
194  running ``make -f Makefile.pre.in boot`` and ``make && make install``.
195
196* For more details read the documentation at the top of ``Makefile.pre.in``.
Note: See TracBrowser for help on using the repository browser.