root/trunk/INSTALL

# $Id$

INSTALLATION INSTRUCTIONS


Quick Start
-----------

For platform specific install guides see:

  http://trac.mapnik.org/wiki/MapnikInstallation

Install needed dependencies::

  $ sudo apt-get install libboost* libicu* libfreetype* proj # see below for full list
  $ cd ~/src/mapnik

Configure the build setup::

  $ python scons/scons.py configure

Build Mapnik source code::

  $ python scons/scons.py

Install Mapnik library and python bindings::

  $ sudo python scons/scons.py install

If on Linux then run:

  $ sudo ldconfig

Run python interpreter and check installation::

  >>> import mapnik
  Traceback (most recent call last):
   File "<stdin>", line 1, in <module>
  ImportError: No module named mapnik
  >>>

If you get this error ensure that Mapnik in is your PYTHONPATH.

Otherwise your setup is ready. You can now visit http://trac.mapnik.org/wiki/GettingStarted for a basic tutorial.

For help with using SCons see: http://trac.mapnik.org/wiki/UsingScons

For troubleshooting errors see: http://trac.mapnik.org/wiki/InstallationTroubleshooting.


Prerequisites
-------------

First, here is a quick list of the required software dependencies:

- Linux/UNIX with g++ compiler
- Python 2.2 or greater to build Mapnik
    - Python 2.4 for python bindings (see below)
- libboost >= 1.41.0 or greater with the following libraries included:
    - system
    - thread
    - filesystem
    - regex
    - iostreams
    - python - required only for python bindings (see below)
- libicu >= 1.4- International Components for Unicode
- libpng - PNG Graphics
- libjpeg - JPEG Graphics
- libtiff - TIFF Graphics 
- libz - Compression
- libfreetype2 - Font support (Install requires freetype-config)
- libxml2 - XML parsing (Install requires xml2-config)
- proj - PROJ.4 Projection library

Second, here are the optional software dependencies:

- Python 2.4 or greater for Python language bindings
- Boost 'python', required for binding Python language bindings
- Boost 'program_options' for shapeindex executable support
- Cairo - Graphics library for PDF, PS, and SVG formats
    - pkg-config - Required for building with cairo support
    - cairomm - C++ bindings for cairo
    - pycairo - Python bindings for cairo
- libpq - PostgreSQL libraries (For PostGIS plugin support)
- libgdal - GDAL/OGR input (For gdal and ogr plugin support)
- libsqlite3 - SQLite input (needs RTree support) (sqlite plugin support)
- libocci - Oracle input plugin support
- libcurl - OSM input plugin support

If your system does NOT have one of these installed, you will need to install the mandatory ones at the very least before proceeding further.

Instructions for installing many of these dependencies on various platforms can be found at the Mapnik Community Wiki (http://trac.mapnik.org/wiki/MapnikInstallation).

On Linux and Mac OS, package management systems (such as apt for debian or macports for darwin) can be used to install most or all dependencies, but source installs may be preferrable. This is particularly true for libraries that a required for the Python bindings, where source installs may be the best way to ensure that the same python version us linked to Boost, Cairo, and Mapnik.

Note: a minimum of 256MB of RAM is recommended for the build process.


Building
--------

Once you've installed the required software packages, the simplest way to build Mapnik is to run SCons (The software builder) without any options::

  $ cd ~/src/mapnik
  $ python scons/scons.py configure
  $ python scons/scons.py # will build sources

This should compile and link the mapnik library as well as the input plugins and the python language binding (if possible).  If any mandatory dependencies are not found the build will fail, and you will need to specify custom paths to your libraries and include files.

SCons accepts a variety of options to customize your build.  This allows you to specify which components are compiled, where to find dependencies, where to install mapnik, and so on.

To see the list of available options, from the root of the source distribution, run::

  $ python scons/scons.py -h

For example, if you compiled your own set of Boost libraries, you might use::

  $ python scons/scons.py configure BOOST_INCLUDES=/usr/local/include/ BOOST_LIBS=/usr/local/lib

Or if you installed ICU from source and you'd like to build Mapnik in Debug mode you might use::

  $ python scons/scons.py configure DEBUG=True ICU_INCLUDES=/usr/local/include ICU_LIBS=/usr/local/lib

For more details on all the options see: http://trac.mapnik.org/wiki/UsingScons

Note: the Python used to run SCons does NOT have to be the same as the one used for the python bindings.


Installation
------------

Once the build has successfully completed, you can install the various files on your system by executing::

  $ sudo python scons/scons.py install

By default, everything will be installed under the PREFIX '/usr/local' as such::

  $PREFIX/lib: libmapnik.so (.dylib on mac os)
  $PREFIX/lib/mapnik/input: input plug-ins
  $PREFIX/include: mapnik include files
  $PREFIX/bin: shapeindex utility
  $PYTHON_PREFIX/lib/python$PYTHON_VERSION/site-packages/mapnik: Python bindings

If you're using the default PREFIX, you will most likely need to be root to perform the install.


Testing Installation
--------------------

First, try importing the Mapnik python module in a python interpreter, and make sure it does so without errors::

  $ python
  Python 2.5.1 (r251:54863, Jan 17 2008, 19:35:17) 
  [GCC 4.0.1 (Apple Inc. build 5465)] on darwin
  Type "help", "copyright", "credits" or "license" for more information.
  >>> import mapnik
  >>> 

Then, try rendering the demo map, included in the Mapnik source code::

  $ cd demo/python
  $ python rundemo.py 

If the resulting maps look good, this indicates the core components of Mapnik are installed properly, as well as the Shapefile plugin, Unicode text support (ICU), and re-projection support using Proj.

For further tests see the `tests` folder within the Mapnik source code.


Learning Mapnik
---------------

For Users:
  - Visit http://trac.mapnik.org/wiki/LearningMapnik for basic tutorials on making maps with Mapnik using the Python bindings.

For Developers:
  - Visit http://trac.mapnik.org/#DevelopersCorner for resources for getting involved with Mapnik development.


Mapnik Community
----------------

Mapnik has an active community of talented users and developers making amazing maps.

If you are looking for further help on installation or usage and you can't find what you are looking for from searching the users list archives (http://lists.berlios.de/pipermail/mapnik-users/) or the trac wiki (http://trac.mapnik.org/), feel free to join the Mapnik community and introduce yourself.

You can get involved by:
  - Subscribing to the mapnik-users list: http://lists.berlios.de/mailman/listinfo/mapnik-users
  - Subscribing to the mapnik-developers list: http://lists.berlios.de/mailman/listinfo/mapnik-devel
  - Joining the #mapnik channel on irc://irc.freenode.net/mapnik
  - Signing up as a user or contributer at http://www.ohloh.net/p/mapnik/  


A note on projection support
----------------------------

Mapnik's core C++ library and map rendering engine support on-the-fly cartographic
reprojections.

Here is an example on how to use it::

  >>> import mapnik
  >>> p = mapnik.Projection('+init=epsg:27700') # British National Grid
  >>> p.forward(mapnik.Coord(-1.125,51.75))
  Coord(460396.920899,206113.214203) # reprojected coordinate x, y pair
  >>> p.forward(mapnik.Envelope(-1.125,51.75,-1.0,50.75))
  Envelope(461721.365661,94917.0749406,469024.861457,206224.090767) # reprojected extent


The Projection() instance provides inverse() and forward() methods.  For details on the possible parameters,
see the PROJ.4 documentation.