source: trunk/docs/install.txt @ 351

Last change on this file since 351 was 351, checked in by darcy, 11 years ago

Remove mention of mx.DateTime? package.

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