This is the Mod_Python README file. It consists of the following parts:


1. Getting Started
2. New in 3.0
3. Migrating from Mod_Python 2.7.8
4. OS Hints



1. Getting Started

See the HTML documentation in the doc-html directory for installation
instructions and documentation.

If you can't read instructions:

	$ ./configure --with-apxs=/usr/local/apache/sbin/apxs

	$ make
	$ su
	# make install

	Edit httpd.conf like instructions at the end of "make install"
	tell you.

	If the above worked - read the tutorial in the doc directory.


2. New in 3.0

o  Compatibility with Apache Httpd 2.0 and Python 2.2. (Apache Httpd
   1.3 and versions of Python prior to 2.2 will not work.)
o  Support for filters (HTTP content only).
o  Support for connection handlers allowing for implementation of
   layer 4 protocols.
o  Python*Handler directives can now be assigned to specific file
   extensions.
o  The publisher handler supports default module and method names
   allowing for cleaner more intuitive url's.
o  A basic test suite.
o  Many other miscellaneous and internal changes.

3. Migrating from Mod_Python 2.7.8.

First, this version of Mod_Python requires Apache Httpd 2, and Python
2.2. (Python 2.2.2 and Apache Httpd 2.0.43 are latest at the time of
this writing). Please make sure you read the appropriate docs to
understand the impact of upgrading both of those, especially upgrading
httpd. Check out http://httpd.apache.org/docs-2.0/upgrading.html.

Some changes in Mod_Python may impact your existing code:

   When configuring/compiling, note that --with-python argument of
   ./configure now takes the path to a Python executable, rather than
   a directory where the source is. The option of having a source
   directory is no longer supported. If you want a separate version of
   Python for use with mod_python, you must have it installed.

   Apache 2 will use threads by default, and so will Python. The old
   warnings about threads no longer apply, for the most part you
   shouldn't worry about it. 

   The user name is now req.user instead of req.connection.user. 

   There is no need for the req.send_http_header() method. It is still
   there for backwards compatibility, but it is a noop. Httpd automatically
   sends out headers as soon as the first byte of output comes through.

   The request object no longer has a _req member. _req was undocumented and
   shouldn't have been used, but if you were using it anyway, your
   code will break. 

   It appears that req.server.port is 0 always, but if you need the local
   port number, you can look at req.connection.local_addr.

4. OS Hints

FreeBSD:        

Apache has to be compiled with threads, even if using the prefork MPM
(recommended). In the ports collection, edit the Makefile to add
--enable-threads in the CONFIGURE_ARGS section.  This has been tested
on FreeBSD 4.7; it is possible that earlier versions of FreeBSD may
have issues with httpd's use of threads.

Mac OS X/Darwin:

(Disclaimer: I am not an expert on Darwin, if you see something
incorrect or have suggestions, please mail the dev list. This worked
for me on OS X 10.2.2, fink Python 2.2.1 and httpd 2.0.43 compiled
from source)

1. Libtool that comes with OS X 10.2.2 or earlier is buggy. Here is a patch to fix it. 

--- /usr/bin/glibtool.orig  Fri Nov 15 16:14:59 2002
+++ /usr/bin/glibtool    Fri Nov 15 16:16:36 2002
@@ -181,7 +181,7 @@
 old_archive_from_expsyms_cmds=""
 
 # Commands used to build and install a shared archive.
-archive_cmds="\$nonopt \$(test \\\"x\$module\\\" = xyes && echo -bundle || echo -dynamiclib) \$allow_undefined_flag -o \$lib \$libobjs \$deplibs\$linker_flags -install_name \$rpath/\$soname \$verstring"
+archive_cmds="\$nonopt \$(test x\$module = xyes && echo -bundle || echo -dynamiclib -install_name \$rpath/\$soname) \$allow_undefined_flag -o \$lib \$libobjs \$deplibs\$linker_flags \$verstring"
 archive_expsym_cmds=""
 postinstall_cmds=""
 postuninstall_cmds=""
--- /usr/share/aclocal/libtool.m4.orig     Fri Nov 15 16:18:23 2002
+++ /usr/share/aclocal/libtool.m4  Fri Nov 15 16:18:45 2002
@@ -1580,7 +1580,7 @@
     # FIXME: Relying on posixy $() will cause problems for
     #        cross-compilation, but unfortunately the echo tests do not
     #        yet detect zsh echo's removal of \ escapes.
-    archive_cmds='$nonopt $(test "x$module" = xyes && echo -bundle || echo -dynamiclib) $allow_undefined_flag -o $lib $libobjs $deplibs$linker_flags -install_name $rpath/$soname $verstring'
+    archive_cmds='$nonopt $(test x$module = xyes && echo -bundle || echo -dynamiclib -install_name $rpath/$soname) $allow_undefined_flag -o $lib $libobjs $deplibs$linker_flags $verstring'
     # We need to add '_' to the symbols in $export_symbols first
     #archive_expsym_cmds="$archive_cmds"' && strip -s $export_symbols'
     hardcode_direct=yes

Note that the Fink libtool (1.4.2-5) has a bug too. The Fink libtool
is half way there in that it will work with gcc2, but gcc3 does not
allow -install_name without -dynamiclib. I don't provide a patch for
Fink libtool since it's so easy to just fix it by manually editing the
file.

2. Now that libtool situation is fixed, rebuild httpd. Make sure to
rerun ./buildconf before ./configure. Also make sure --enable-so is
specified as argument to ./configure.

3. On Darwin, libpython cannot be linked statically with mod_python
using libtool. libpython has to be a dynamic shared object. The Python
distribution does not provide a way of building libpython as a shared
library, but the Fink Python distribution comes with one
(/sw/lib/python2.2/config/libpython2.2.dylib), so the easiest thing is
to install Python from Fink (fink.sourceforge.net).

4. Now configure, build, install mod_python like you normally would:
  ./configure --with-apxs=/where/ever/apxs
  make
  (su)
  make install

5. You are not out of the woods yet. Python has a lot of its built-in
modules as shared libraries (or mach-o bundles to be precise). They
are linked with "--bundle_loader python.exe", which means that many
symbols are expected to be defined in the executable loading the
bundle. Such would not be the case when the module is loaded from
within mod_python, and therefore you will get "undefined symbol"
errors when trying to import a built-in module, e.g. "time".

I don't know what the *right* solution for this is, but here is a
trick that works: define DYLD_FORCE_FLAT_NAMESPACE environment
variable prior to launching httpd.