source: trunk/docs/install.txt @ 516

Last change on this file since 516 was 516, checked in by D'Arcy J.M. Cain, 7 years ago

Seems that keyword expansion was never set up on these files.

  • Property svn:keywords set to Author Date Id Revision
File size: 6.4 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.7 and
19PostGreSQL 9.2. Older version should work as well, but you will need
20at least Python 2.5 and PostgreSQL 8.3.
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
60`Distutils <http://docs.python.org/install/>`_.
61
62Download and unpack the PyGreSQL source tarball if you haven't already done so.
63
64Type the following commands to build and install PyGreSQL::
65
66    python setup.py build
67    python setup.py install
68
69If you are using `MinGW <http://www.mingw.org>`_ to build PyGreSQL under
70Microsoft Windows, please note that Python newer version 2.3 is using msvcr71
71instead of msvcrt as its common runtime library. You can allow for that by
72editing the file ``%MinGWpath%/lib/gcc/%MinGWversion%/specs`` and changing
73the entry that reads ``-lmsvcrt`` to ``-lmsvcr71``. You may also need to copy
74``libpq.lib`` to ``libpq.a`` in the PostgreSQL ``lib`` directory. Then use
75the following command to build and install PyGreSQL::
76
77    python setup.py build -c mingw32 install
78
79Now you should be ready to use PyGreSQL.
80
81Compiling Manually
82------------------
83
84The source file for compiling the dynamic module is called pgmodule.c.
85You have two options. You can compile PyGreSQL as a stand-alone module
86or you can build it into the Python interpreter.
87
88Stand-Alone
89-----------
90
91* In the directory containing ``pgmodule.c``, run the following command::
92
93    cc -fpic -shared -o _pg.so -I$PYINC -I$PGINC -I$PSINC -L$PGLIB -lpq pgmodule.c
94
95  where you have to set::
96
97    PYINC = path to the Python include files
98            (usually something like /usr/include/python)
99    PGINC = path to the PostgreSQL client include files
100            (something like /usr/include/pgsql or /usr/include/postgresql)
101    PSINC = path to the PostgreSQL server include files
102            (like /usr/include/pgsql/server or /usr/include/postgresql/server)
103    PGLIB = path to the PostgreSQL object code libraries (usually /usr/lib)
104
105  If you are not sure about the above paths, try something like::
106
107    PYINC=`find /usr -name Python.h`
108    PGINC=`find /usr -name libpq-fe.h`
109    PSINC=`find /usr -name postgres.h`
110    PGLIB=`find /usr -name libpq.so`
111
112  If you have the ``pg_config`` tool installed, you can set::
113
114    PGINC=`pg_config --includedir`
115    PSINC=`pg_config --includedir-server`
116    PGLIB=`pg_config --libdir`
117
118  Some options may be added to this line::
119
120    -DNO_DEF_VAR   no default variables support
121    -DNO_DIRECT    no direct access methods
122    -DNO_LARGE     no large object support
123    -DNO_PQSOCKET  if running an older PostgreSQL
124
125  On some systems you may need to include ``-lcrypt`` in the list of libraries
126  to make it compile.
127
128* Test the new module. Something like the following should work::
129
130    $ python
131
132    >>> import _pg
133    >>> db = _pg.connect('thilo','localhost')
134    >>> db.query("INSERT INTO test VALUES ('ping','pong')")
135    18304
136    >>> db.query("SELECT * FROM test")
137    eins|zwei
138    ----+----
139    ping|pong
140    (1 row)
141
142* Finally, move the ``_pg.so``, ``pg.py``, and ``pgdb.py`` to a directory in
143  your ``PYTHONPATH``. A good place would be ``/usr/lib/python/site-packages``
144  if your Python modules are in ``/usr/lib/python``.
145
146Built-in to Python interpreter
147------------------------------
148
149* Find the directory where your ``Setup`` file lives (usually in the ``Modules``
150  subdirectory) in the Python source hierarchy and copy or symlink the
151  ``pgmodule.c`` file there.
152
153* Add the following line to your 'Setup' file::
154
155    _pg  pgmodule.c -I$PGINC -I$PSINC -L$PGLIB -lpq
156
157  where::
158
159    PGINC = path to the PostgreSQL client include files (see above)
160    PSINC = path to the PostgreSQL server include files (see above)
161    PGLIB = path to the PostgreSQL object code libraries (see above)
162
163  Some options may be added to this line::
164
165    -DNO_DEF_VAR   no default variables support
166    -DNO_DIRECT    no direct access methods
167    -DNO_LARGE     no large object support
168    -DNO_PQSOCKET  if running an older PostgreSQL (see above)
169
170  On some systems you may need to include ``-lcrypt`` in the list of libraries
171  to make it compile.
172
173* If you want a shared module, make sure that the ``shared`` keyword is
174  uncommented and add the above line below it. You used to need to install
175  your shared modules with ``make sharedinstall`` but this no longer seems
176  to be true.
177
178* Copy ``pg.py`` to the lib directory where the rest of your modules are.
179  For example, that's ``/usr/local/lib/Python`` on my system.
180
181* Rebuild Python from the root directory of the Python source hierarchy by
182  running ``make -f Makefile.pre.in boot`` and ``make && make install``.
183
184* For more details read the documentation at the top of ``Makefile.pre.in``.
Note: See TracBrowser for help on using the repository browser.