/
modpython2.tex
361 lines (280 loc) · 12.6 KB
/
modpython2.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
\chapter{Installation\label{installation}}
\indexii{installation}{UNIX}
\indexii{mod_python}{mailing list}
\begin{notice}
By far the best place to get help with installation and other issues
is the mod_python mailing list. Please take a moment to join the
mod_python mailing list by sending an e-mail with the word
\samp{subscribe} in the subject to
\email{mod_python-request@modpython.org}.
\end{notice}
\section{Prerequisites\label{inst-prerequisites}}
\begin{itemize}
\item
Python 2.2.1 or later. Earlier versions of Python will not work.
\item
Apache 2.0.40 or later (For Apache 1.3.x, use mod_python version 2.7.x).
\end{itemize}
In order to compile mod_python you will need to have the include files
for both Apache and Python, as well as the Python library installed on
your system. If you installed Python and Apache from source, then you
already have everything needed. However, if you are using prepackaged
software (e.g. Red Hat Linux RPM, Debian, or Solaris packages from
sunsite, etc) then chances are, you have just the binaries and not the
sources on your system. Often, the Apache and Python include files and
libraries necessary to compile mod_python are part of separate
``development'' package. If you are not sure whether you have all the
necessary files, either compile and install Python and Apache from
source, or refer to the documentation for your system on how to get
the development packages.
\section{Compiling\label{inst-compiling}}
\indexii{compiling}{mod_python}
There are two ways in which modules can be compiled and linked to
Apache - statically, or as a DSO (Dynamic Shared Object).
\dfn{DSO} is a more popular approach nowadays and is the recommended
one for mod_python. The module gets compiled as a shared library which
is dynamically loaded by the server at run time.
The advantage of DSO is that a module can be installed without
recompiling Apache and used as needed. A more detailed description of
the Apache DSO mechanism is available at
\url{http://httpd.apache.org/docs-2.0/dso.html}.
\emph{At this time only DSO is supported by mod_python.}
\dfn{Static} linking is an older approach. With dynamic linking
available on most platforms it is used less and less. The main
drawback is that it entails recompiling Apache, which in many
instances is not a favorable option.
\subsection{Running ./configure\label{inst-configure}}
\index{./configure}
The \program{./configure} script will analyze your environment and create custom
Makefiles particular to your system. Aside from all the standard
autoconf stuff, \program{./configure} does the following:
\begin{itemize}
\item
\index{apxs}
\index{./configure!\longprogramopt{with-apxs}}
%\indexii{./configure}{\longprogramopt{with-apxs}}
Finds out whether a program called \program{apxs} is available. This
program is part of the standard Apache distribution, and is necessary
for DSO compilation. If apxs cannot be found in your \envvar{PATH} or in
\filenq{/usr/local/apache/bin}, DSO compilation will not be available.
You can manually specify the location of apxs by using the
\longprogramopt{with-apxs} option, e.g.:
\begin{verbatim}
$ ./configure --with-apxs=/usr/local/apache/bin/apxs
\end{verbatim}
%$ keep emacs happy
It is recommended that you specify this option.
\item
\index{libpython.a}
Checks your Python version and attempts to figure out where
\program{libpython} is by looking at various parameters compiled into
your Python binary. By default, it will use the \program{python}
program found in your \envvar{PATH}.
\index{./configure!\longprogramopt{with-python}}
%\indexii{./configure}{\longprogramopt{with-python}}
If the first Python binary in the path is not suitable or not the one
desired for mod_python, you can specify an alternative location with the
\longprogramopt{with-python} option, e.g:
\begin{verbatim}
$ ./configure --with-python=/usr/local/bin/python2.3
\end{verbatim}
%$ keep emacs happy
\item
\index{flex}
Attempts to locate \program{flex} and determine its version.
If \program{flex} cannot be found in your \envvar{PATH} \program{configure}
will fail. If the wrong version is found \program{configure} will generate a warning.
You can generally ignore this warning unless you need to re-create
\filenq{src/psp_parser.c}.
The parser used by psp (See \ref{pyapi-psp}) is written in C generated using
\program{flex}. This requires a reentrant version of \program{flex} which
at this time is 2.5.31. Most platforms however ship with version 2.5.4
which is not suitable, so a pre-generated copy of psp_parser.c is included
with the source. If you do need to compile \filenq{src/psp_parser.c} you
must get the correct \program{flex} version.
\index{./configure!\longprogramopt{with-flex}}
%\indexii{./configure}{\longprogramopt{with-flex}}
If the first flex binary in the path is not suitable or not the one desired
you can specify an alternative location with the \longprogramopt{with-flex}
option, e.g:
\begin{verbatim}
$ ./configure --with-flex=/usr/local/bin/flex
\end{verbatim}
%$ keep emacs happy
\item
\index{python-src}
The python source is required to build the mod_python documentation.
\index{./configure!\longprogramopt{with-python-src}}
%\indexii{./configure}{\longprogramopt{with-python-src}}
You can safely ignore this option unless you want to build the the
documentation. If you want to build the documentation, specify the path
to your python source with the \longprogramopt{with-python-src} option, eg.
\begin{verbatim}
$ ./configure --with-python-src=/usr/src/python2.3
\end{verbatim}
%$ keep emacs happy
\end{itemize}
\subsection{Running make\label{inst-make}}
\begin{itemize}
\item
%If possible, the \program{./configure} script will default to DSO
%compilation, otherwise, it will default to static. To stay with
%whatever \program{./configure} decided, simply run
To start the build process, simply run
\begin{verbatim}
$ make
\end{verbatim}
%$ emacs happy
\end{itemize}
\section{Installing\label{inst-installing}}
\subsection{Running make install\label{inst-makeinstall}}
\begin{itemize}
\item
This part of the installation needs to be done as root.
\begin{verbatim}
$ su
# make install
\end{verbatim}
%$ emacs happy
\begin{itemize}
\item
%For DSO, this will simply copy the library into your Apache \filenq{libexec}
This will simply copy the library into your Apache \filenq{libexec}
directory, where all the other modules are.
%\item
%For static, it will copy some files into your Apache source tree.
\item
Lastly, it will install the Python libraries in \filenq{site-packages} and
compile them.
\end{itemize}
\indexii{make targets}{install_py_lib}
%\indexii{make targets}{install_static}
\indexii{make targets}{install_dso}
\strong{NB:} If you wish to selectively install just the Python libraries
%the static library or the DSO (which may not always require superuser
or the DSO (which may not always require superuser
privileges), you can use the following \program{make} targets:
\programopt{install_py_lib} and \programopt{install_dso}
%\programopt{install_static} and \programopt{install_dso}
\end{itemize}
\subsection{Configuring Apache\label{inst-apacheconfig}}
\begin{itemize}
\item
If you compiled mod_python as a DSO, you will need to tell Apache to
load the module by adding the following line in the Apache
configuration file, usually called \filenq{httpd.conf} or
\filenq{apache.conf}:
\begin{verbatim}
LoadModule python_module libexec/mod_python.so
\end{verbatim}
\index{mod_python.so}
The actual path to \program{mod_python.so} may vary, but make install
should report at the very end exactly where \program{mod_python.so}
was placed and how the \code{LoadModule} directive should appear.
\end{itemize}
\section{Testing\label{inst-testing}}
\strong{Warning :} These instructions are meant to be followed if you are
using mod_python 3.x or later. If you are using mod_python 2.7.x (namely,
if you are using Apache 1.3.x), please refer to the proper documentation.
\begin{enumerate}
\item
Make some directory that would be visible on your web site, for
example, htdocs/test.
\item
Add the following Apache directives, which can appear in either the
main server configuration file, or \filenq{.htaccess}. If you are
going to be using the \filenq{.htaccess} file, you will not need the
\code{<Directory>} tag below (the directory then becomes the one in
which the \filenq{.htaccess} file is located), and you will need to
make sure the \code{AllowOverride} directive applicable to this
directory has at least \code{FileInfo} specified. (The default is
\code{None}, which will not work.)
% the above has been verified to be still true for Apache 2.0
\begin{verbatim}
<Directory /some/directory/htdocs/test>
AddHandler mod_python .py
PythonHandler mptest
PythonDebug On
</Directory>
\end{verbatim}
(Substitute \filenq{/some/directory} above for something applicable to
your system, usually your Apache ServerRoot)
\item
This redirects all requests for URLs ending in \filenq{.py} to the mod_python
handler. mod_python receives those requests and looks for an appropriate
PythonHandler to handle them. Here, there is a single PythonHandler
directive defining mptest as the python handler to use. We'll see next
how this python handler is defined.
\item
At this time, if you made changes to the main configuration file, you
will need to restart Apache in order for the changes to take effect.
\item
Edit \filenq{mptest.py} file in the \filenq{htdocs/test} directory so
that is has the following lines (be careful when cutting and pasting
from your browser, you may end up with incorrect indentation and a
syntax error):
\begin{verbatim}
from mod_python import apache
def handler(req):
req.content_type = 'text/plain'
req.write("Hello World!")
return apache.OK
\end{verbatim}
\item
Point your browser to the URL referring to the \filenq{mptest.py};
you should see \samp{Hello World!}. If you didn't - refer to the
troubleshooting section next.
\item
Note that according to the configuration written above, you can
also point your browser to any URL ending in .py in the test directory.
You can for example point your browser to \filenq{/test/foobar.py}
and it will be handled by \filenq{mptest.py}. That's because you
explicitely set the handler to always be \filenq{mptest}, whatever the
requested file was. If you want to have many handler files named
\filenq{handler1.py}, \filenq{handler2.py}
and so on, and have them accessible on \filenq{/test/handler1.py},
\filenq{/test/handler2.py}, etc., then you have to use a higher level
handler system such as the mod_python publisher (see \ref{tut-pub}),
mpservlets or Vampire. Those are just special mod_python handler
that know how to map requests to a dynamically loaded handler.
\item
If everything worked well, move on to Chapter \ref{tutorial},
\citetitle[tutorial.html]{Tutorial}.
\end{enumerate}
\begin{seealso}
\seeurl{http://home.comcast.net/~d.popowich/mpservlets}{mpservlets}
\seeurl{http://www.dscpl.com.au/projects/vampire}{Vampire}
\end{seealso}
\section{Troubleshooting\label{inst-trouble}}
There are a few things you can try to identify the problem:
\begin{itemize}
\item Carefully study the error output, if any.
\item Check the server error log file, it may contain useful clues.
\item Try running Apache from the command line in single process mode:
\begin{verbatim}
./httpd -X
\end{verbatim}
This prevents it from backgrounding itself and may provide some useful
information.
\item Beginning with mod_python 3.2.0, you can use the mod_python.testhandler
to diagnose your configuration. Add this to your \filenq{httpd.conf} file :
\begin{verbatim}
<Location /mpinfo>
SetHandler mod_python
PythonHandler mod_python.testhandler
</Location>
\end{verbatim}
Now point your browser to the \filenq{/mpinfo} URL
(e.g. \filenq{http://localhost/mpinfo}) and note down the information given.
This will help you reporting your problem to the mod_python list.
\item
Ask on the mod_python list. Make sure to provide specifics such as:
\begin{itemize}
\item Mod_python version.
\item Your operating system type, name and version.
\item Your Python version, and any unusual compilation options.
\item Your Apache version.
\item Relevant parts of the Apache config, .htaccess.
\item Relevant parts of the Python code.
\end{itemize}
\end{itemize}