mapnik/INSTALL

207 lines
7.6 KiB
Text
Raw Normal View History

2006-02-01 00:09:52 +01:00
# $Id$
INSTALLATION INSTRUCTIONS
2008-04-15 09:24:52 +02:00
Quick Start
-----------
2009-03-31 19:46:05 +02:00
For platform specific install guides see:
http://trac.mapnik.org/wiki/MapnikInstallation
Install needed dependencies::
2008-04-15 09:24:52 +02:00
$ sudo apt-get install libboost* libicu* libfreetype* proj # see below for full list
$ cd ~/src/mapnik
2008-04-15 09:24:52 +02:00
2009-02-27 00:47:46 +01:00
Configure the build setup::
$ python scons/scons.py configure
Build Mapnik source code::
2008-04-15 09:24:52 +02:00
$ python scons/scons.py
Install Mapnik library and python bindings::
$ sudo python scons/scons.py install
Run python interpreter and check installation::
>>> import mapnik
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ImportError: No module named mapnik
>>>
2008-04-15 09:24:52 +02:00
If you get this error ensure that Mapnik in is your PYTHONPATH.
2008-04-15 09:24:52 +02:00
Otherwise your setup is ready. You can now visit http://trac.mapnik.org/wiki/GettingStarted for a basic tutorial.
2008-04-15 09:24:52 +02:00
2009-03-31 19:46:05 +02:00
For help with using SCons see: http://trac.mapnik.org/wiki/UsingScons
For troubleshooting errors see: http://trac.mapnik.org/wiki/InstallationTroubleshooting.
2008-04-15 09:24:52 +02:00
Prerequisites
2006-02-01 00:09:52 +01:00
-------------
First, here is a quick list of the required software dependencies:
2006-02-01 00:09:52 +01:00
- Linux/UNIX with g++ compiler
- Python 2.2 or greater to build Mapnik
- Python 2.4 for python bindings (see below)
- libboost 1.34.0 or greater with the following libraries included:
- system (boost >= 1.35 only)
- thread
- filesystem
- regex
- iostreams
- python - required only for python bindings (see below)
2008-04-15 09:24:52 +02:00
- libicu - 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)
2009-03-31 19:46:05 +02:00
- libocci - Oracle input plugin support
- libcurl - OSM input plugin support
2009-03-31 19:46:05 +02:00
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).
2008-04-15 09:24:52 +02:00
2009-03-31 19:46:05 +02:00
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.
2008-04-15 09:24:52 +02:00
2009-03-31 19:46:05 +02:00
Note: a minimum of 256MB of RAM is recommended for the build process.
Building
2006-02-01 00:09:52 +01:00
--------
Once you've installed the required software packages, the simplest way to build Mapnik is to run SCons (The software builder) without any options::
2006-02-01 00:09:52 +01:00
$ cd ~/src/mapnik
2009-03-31 19:46:05 +02:00
$ python scons/scons.py configure
$ python scons/scons.py # will build sources
2006-02-01 00:09:52 +01:00
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.
2006-02-01 00:09:52 +01:00
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.
2006-02-01 00:09:52 +01:00
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::
2006-02-01 00:09:52 +01:00
2009-03-31 19:46:05 +02:00
$ python scons/scons.py configure BOOST_TOOLKIT=gcc43 BOOST_INCLUDES=/usr/local/include/boost-1_38 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
2006-02-01 00:09:52 +01:00
2009-03-31 19:46:05 +02:00
For more details on all the options see: http://trac.mapnik.org/wiki/UsingScons
2008-04-15 09:24:52 +02:00
2009-03-31 19:46:05 +02:00
Note: the Python used to run SCons does NOT have to be the same as the one used for the python bindings.
2008-04-15 09:24:52 +02:00
2006-02-01 00:09:52 +01:00
Installation
------------
Once the build has successfully completed, you can install the various files on your system by executing::
2006-02-01 00:09:52 +01:00
$ python scons/scons.py install
2006-02-01 00:09:52 +01:00
By default, everything will be installed under the PREFIX '/usr/local' as such::
2006-02-01 00:09:52 +01:00
2009-03-31 19:46:05 +02:00
$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
2006-02-01 00:09:52 +01:00
If you're using the default PREFIX, you will most likely need to be root to perform the install.
2008-04-15 09:24:52 +02:00
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.
2005-06-14 17:06:59 +02:00
2008-04-15 09:24:52 +02:00
Learning Mapnik
---------------
2008-04-15 09:24:52 +02:00
For Users:
- Visit http://trac.mapnik.org/wiki/GettingStarted 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.
2008-04-15 09:24:52 +02:00
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/
2008-04-15 09:24:52 +02:00
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::
2008-04-15 09:24:52 +02:00
>>> from mapnik import Projection, Coord
>>> p = Projection('+init=epsg:27700') # British National Grid
>>> p.forward(Coord(-1.125,51.75))
Coord(460396.920899,206113.214203) # reprojected coordinate x, y pair
2009-03-31 19:46:05 +02:00
>>> p.forward(Envelope(-1.125,51.75,-1.0,50.75))
Envelope(461721.365661,94917.0749406,469024.861457,206224.090767) # reprojected extent
2008-04-15 09:24:52 +02:00
The Projection() instance provides inverse() and forward() methods. For details on the possible parameters,
see the PROJ.4 documentation.