.. $Id: README 6843 2007-09-05 22:49:32Z hobu $

Python MapScript for MapServer 5.0 README
================================================================

:Author: Howard Butler
:Contact: hobu.inc@gmail.com
:Author: Sean Gillies
:Contact: sgillies@frii.com
:Revision: $Revision: 6560 $
:Date: $Date: 2007-08-11 21:41:45 -0500 (Sat, 11 Aug 2007) $

The Python mapscript module provides users an interface to MapServer
classes on any platform, and has been well tested on Python versions
2.2-2.4.


Building the Mapscript Module
-----------------------------

Before you begin, it's worth spending a few minutes to read the
docs about Python distutils:

    http://www.python.org/doc/current/dist/dist.html

Now that you know what distutils does, use it like
::

    $ python setup.py build


Building C Extension Wrappers
-----------------------------

If you are building the mapscript module from CVS, not from a release, the
C extension wrappers will be absent and must then be generated using SWIG,
the Simplified Wrapper and Interface Generator, http://www.swig.org.  SWIG
version 1.3.29 or higher is recommended.

From the mapscript/python directory execute
::

    $ swig -python -shadow -o mapscript_wrap.c ../mapscript.i

and then proceed to the build step explained above.  If you are using
Python 2.2 or 2.3, you should add a -modern option which produces a higher
performance module.  ::

    $ swig -python -shadow -modern -o mapscript_wrap.c ../mapscript.i

If you have SWIG version 1.3.31 or greater, you can add in some of SWIG's 
optimizations to squeeze more performance out of the bindings ::

    $ swig -python -shadow -modern -templatereduce -fastdispatch -fvirtual -fastproxy 
      -modernargs -castmode -dirvtable -fastinit -fastquery -noproxydel -nobuildnone 
      -o mapscript_wrap.c ../mapscript.i
    
Testing
-------

Make the appropriate edits to tests/test.map under the mapserver directory,
change directory from mapscript/python and execute ::

    $ cd tests/cases
    $ python runalltests.py -v

The tests can (and should) be run before the module is installed.

Installing
----------

As root or superuser
::
    
    $ python setup.py install

That's it!
  
Credits
-------

Steve Lime (developer)
Sean Gillies (developer)
Frank Warmerdam (developer)
Howard Butler (developer)
Norman Vine (cygwin and distutils guru)
Tim Cera (install)
Michael Schultz (documentation)

MapScript is now using code from gdmodule 

  http://newcenturycomputers.net/projects/gdmodule.html

which makes possible some new and cool imageObj tricks.  The use
this code is **greatly** appreciated and MapServer developers look
forward to being able to share advances with the gdmodule
developers.