= Installation =

== Dependencies ==
[http://www.python.org Python 2.5]
    Although modu should run properly under Python 2.4,
    there are some memory release issues that can be a problem for long-
    running applications, such as web servers.
[http://www.zope.org/Products/ZopeInterface Zope Interface]
    Zope.Interface is required by both Twisted
    and modu, but should be considered an essential part of any Python
    installation.
[http://www.twistedmatrix.com Twisted]
    As a matter of personal preference, I run Twisted
    from the most recent SVN checkout, but the most recent stable release
    should be fine.
[http://www.cheetahtemplate.org Cheetah Template]
    Cheetah is the default template engine for modu. Other engines are
    available, but currently unsupported.
[http://www.mysql.com MySQL 5]
    modu is probably about 95% database-agnostic, but at this time still
    has a dependency on MySQL 5.
[http://sourceforge.net/projects/mysql-python MySQLdb 1.2.2 or greater]
    Earlier versions of MySQLdb have a bug in their
    unicode handling. Note that even if you're experimenting with alternate
    DB engines, there's still a dependency on MySQLdb when generating queries.
[http://httpd.apache.org Apache 2.2] (optional)
    There are two supported deployment options for Apache, either through
    a reverse proxying setup through the twisted.web server, or using
    [http://code.google.com/p/modwsgi mod_wsgi]. [http://www.modpython.org mod_python] may work, but is not actively supported at this
    time

== Installation ==

You should be able to install the items above in the order listed. There are no special configuration details for the dependencies in general, but there are a number of version- or platform-specific issues you might encounter.

Once the dependencies are all in place, you can uncompress a recent modu tarball in some convenient location. Assuming root privileges, install the modu toolkit with:

{{{
    python setup.py install
}}}

'''NOTE:''' The `setup.py` installation script is not always terribly up-to-date, and is not generally used by the current developers when creating a new installation. That hopefully will change in the future, but for now it's best to follow an alternative installation process, outlined here:

 1. First uncompress the modu tarball, or [http://modu.bubblehouse.org/downloads check out the modu module from SVN]
 2. In your Python installation's `site-packages` directory, create a file called `modu.pth`, with a single line indicating the absolute path to your modu isntallation directory.
 3. Create a symlink in `/usr/local/bin` to the `modu/bin/mkmodu.py` script.
 4. Set the permissions of the `modu/bin/mkmodu.py` script to be executable, if it's not already.

=== Twisted Python on Mac OS X 10.5.1 ===

The stock Leopard install includes a partial install of Twisted in:

{{{
    /System/Library/Frameworks/Python.framework/Versions/2.5/Extras
}}}

If you attempt to run Twisted out of the SVN module itself (say, for development
purposes), you can run into problems where the partial installed version preempts
the newly installed copy.

To fix this, you can place the following in a .pth file inside your site-packages directory:

{{{
import sys; sys.path = [s for s in sys.path 
                        if s != '/Library/Python/2.5/site-packages']
import sys; sys.path.insert(0, '/Library/Python/2.5/site-packages')
import sys; sys.path.insert(0, '/usr/local/dram/Twisted')
/usr/local/dram/modu
}}}

The first line removes the site-packages directories (to prevent duplicates),
the next two lines insert the new paths at the top of the system path, and the
last line adds a directory to the end of the system path.

For more information, consult the [http://docs.python.org/lib/module-site.html Python documentation].


=== MySQLdb on Mac OS X 10.5.1 ===

There seems to be an issue with MySQLdb 1.2.2 (the Python MySQL driver) and
Mac OS X Leopard. The symptom is this error:

{{{
    In file included from /usr/local/mysql/include/mysql.h:43,
                     from _mysql.c:40:
    /usr/include/sys/types.h:92: error: duplicate 'unsigned'
    /usr/include/sys/types.h:92: error: two or more data types
                     in declaration specifiers
    error: command 'gcc' failed with exit status 1
}}}

You'll need to edit _mysql.c and comment out or remove the following lines:

{{{
    #ifndef uint
    #define uint unsigned int
    #endif
}}}

Also, importing the MySQLdb module in Python may raise an exception about
a 'missing image'. If so, you'll also need to create this impossible-
looking symlink:

{{{
    ln -s /usr/local/mysql/lib /usr/local/mysql/lib/mysql
}}}