Installing Mapnik on Mac OS X

Known Issues

  • There are several known issues with building Mapnik on Mac OS X
  • It is entirely possible to run Mapnik on Mac 10.4 and 10.5 but some users have experienced the following problems:
    • Mapnik does not correctly read the map Envelope(extent) and gets caught in infinite loop during shapefile processing - April 17 - May be related to PPC architecture. See Ticket #92
    • NoneType Error occurs in python bindings - April 21 & April 18. The NoneType error may be due to a previously installed version of Python (possible from Tiger to Leopard Upgrade) that left frameworks in /Library/Frameworks/Python.framework. Remove that folder, and rebuild mapnik. NOTE: Only do this if you can confirm that this is not the current location of your system Python.
  • Keep in mind that installation on most linux distros is an easier starting point. For example, on Ubuntu many of the dependencies are either pre-installed or readily available via the synaptic package manager. Macports and Fink hypothetically offer similar convience but conflicts between local source installs and port/fink installs are pita's for mapnik mac users.
  • If you are new to compiling source code or having trouble getting started on a mac, you'll find that building Mapnik on a linux system is a more friendly place to start.

Notes on These Instructions

  • Prerequisites are mandatory unless noted
  • Instructions here focus on terminal commands. If you are new to command line usage, read up on using the Bash shell and the mac native Terminal.app.
  • The Wget command is used below to download source packages and is not pre-installed on Mac OS.
  • The $ indicates a normal command prompt in the shell.
  • The # indicates a command that likely needs to be run by a superuser.
  • The ## indicates code comments that are not executed.

Prerequisites

  • Intel or PPC Mac
  • g++ compiler (default compiler should be fine)
  • The Latest Mapnik Source - 0.5.1
    • Download stable release 0.5.1 - Mapnik Source 0.5.1
    • Checkout the current repository with subversion: 
      svn co svn://svn.mapnik.org/trunk mapnik

  • Boost - C++ Libraries
    • Thread - libboost_thread-mt.dylib
    • System - config.hpp (for different operating systems support)
    • Filesystem - libboost_filesystem.dylib
    • regex (regular expressions) - libboost_regex.dylib
    • Iostreams (input/output) - libboost_iostreams.dylib
    • Program Options - program_options.hpp
    • python - libboost_python.dylib
    • Note: Boost Jam (bjam) needed for boost source build

Instructions

Short Version

1. Install dependencies (Good luck! See below...)

2. Optional: within the Mapnik source directory run this command to get your build options:

3. Then run scons to build:

  • Note: this will only work if all your required dependencies are in the default locations (near impossible on Mac OS)
  • Some packages are located in scons using pkg-config (so make sure that binary in is your path)
  • Set custom directives with flags like PGSQL_INCLUDES=/usr/local/pgsql/include PGSQL_LIBS=/usr/local/pgsql/lib to point to custom locations 
    $ python scons/scons.py

4. Once scons can find all needed dependencies it will compile Mapnik locally. To install then issue: 

$ python scons/scons.py install [and any of the flags you needed to find dependencies]

5. Optional: Run this command to clear out the local scons build if you already attempted, unsuccessfully, to build: 

$ python scons/scons.py -c

6. Optional: if you are rebuilding Mapnik due to compile problems or updgrading it may help to first delete your mapnik libs and python bindings: 

## If you ran scons using the system python the PYTHON_PREFIX will likely be equivalent to: /usr/lib/python2.5/site-packages/
$ export PYTHON_PREFIX=/System/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/site-packages
## The PREFIX will be /usr/local by default or your custom location
$ export PREFIX=/usr/local
## Uninstall the Python `mapnik` module.
$ sudo rm -fr $PYTHON_PREFIX/mapnik
## Uninstall the mapnik libs, includes, and bin
$ sudo rm -fr $PREFIX/include/mapnik
$ sudo rm -fr $PREFIX/lib/mapnik
$ sudo rm -f $PREFIX/lib/libmapnik.*
$ sudo rm $PREFIX/bin/shapeindex

Full Instructions

Download Mapnik

1. Download the Mapnik source code from svn 

$ svn co svn://svn.mapnik.org/trunk mapnik_svn
$ cd mapnik_svn

or the stable release source code: 

$ wget http://prdownload.berlios.de/mapnik/mapnik_src-0.5.1.tar.gz 
$ tar xvf mapnik_src-0.5.1.tar
$ cd mapnik-0.5.1/

2. Read over the INSTALL instructions for your version 

open INSTALL # Doc in the root of Mapnik download

Optional Installs

3. Install Proj.4, PostgreSQL/PostGIS, and GDAL if necessary

  • Install Proj and Datum data 
    $ wget ftp://ftp.remotesensing.org/proj/proj-4.6.0.tar.gz
$ tar xzf proj-4.6.0.tar.gz
$ wget ftp://ftp.remotesensing.org/proj/proj-datumgrid-1.3.tar.gz
$ cd proj-4.6.0/nad
$ tar xzf ../../proj-datumgrid-1.3.tar.gz
$ ./configure
$ make
# make install
  • Install PostgreSQL and PostGIS binaries from - kyngchaos.com or build from source:
    • You can build PostgreSQL from source just like any other linux/unix system - Postgres Docs
    • Next build PostGIS source (Install GEOS first if you wish to use Spatial Operations in Postgis separately - http://code.djangoproject.com/wiki/GeoDjangoInstall#GEOS) 
      $ wget http://postgis.refractions.net/download/postgis-1.3.3.tar.gz
$ tar xzf postgis-1.3.3.tar.gz
$ cd postgis-1.3.3
$ ./configure --with-geos --with-proj # these flags are recommend but not needed for Mapnik
$ make
# make install
  • Install GDAL binary frameworks from - kyngchaos.com or build from source: 
    $ wget http://download.osgeo.org/gdal/gdal-1.5.0.tar.gz
$ tar xzf gdal-1.5.0.tar.gz
$ cd gdal-1.5.0
$ ./configure # --with-package (lots of available options here to support various raster formats)
$ make
# make install

Install Necessary Libraries

4. Install all the imaging, character encoding, font, compression, and parsing libraries

  • This can be done with Macports, Fink, or by source (recommended).
  • The image libraries should already be installed if you used the Frameworks from kyngchaos.com for GDAL
    • You will still need to specify their locations in the scons build process like:
      • TIFF_LIBS=/Library/Frameworks/UnixImageIO.framework/Versions/Current/unix/lib
      • TIFF_INCLUDES=/Library/Frameworks/UnixImageIO.framework/Versions/Current/unix/include
    • And you may need to specify in your .bash_profile:
      • export DYLD_LIBRARY_PATH=/Library/Frameworks/UnixImageIO.framework/Versions/Current/unix/lib
  • Detailed descriptions - TO DO / FIXME

Install Boost

5. Install Boost using Bjam

  • You can install boost 1.34 with Macports: 
    $ port info boost-jam boost # optional: this is to check that these exist and see their details
# port install boost-jam # must install bjam manually first, due to [http://trac.macosforge.org/projects/macports/ticket/13714 Macports bug]
# port install -v boost +python25 +icu
    • Prepare for a long wait and lots of CPU!
    • Macports should automatically download any dependencies needed for Boost
  • Or (recommend) install from source (thanks jbronn) like so:
    • Use the bjam not the configure script to build.
    • If you have a dual-core system you can add the -j2 flag to both bjam and scons to take advantage of both cores: 
      $ wget http://downloads.sourceforge.net/boost/boost_1_35_0.tar.bz2
$ tar xjvf boost_1_35_0.tar.bz2
$ cd boost_1_35_0
$ export BOOST=`pwd`
$ cd tools/jam/src
$ ./build.sh darwin
$ cd bin.macosxx86/
$ export PATH=`pwd`:$PATH
$ cd $BOOST
$ bjam --toolset=darwin \
  --with-thread --with-filesystem --with-iostreams \
  --with-regex --with-program_options --with-python \
  --with-system stage
$ sudo bjam --toolset=darwin \
  --with-thread --with-filesystem --with-iostreams \
  --with-regex --with-program_options --with-python \
  --with-system install
  • If you encounter errors later on during the scons stage (complaining about not finding boost filesystem) then you should create symlinks to each of the boost files 
        ln -s /usr/local/lib/libboost-filesystem-mt-1_35.dylib /usr/local/lib/libboost-filesystem-mt.dylib
    ln -s /usr/local/lib/libboost-python-mt-1_35.dylib /usr/local/lib/libboost-python-mt.dylib
.. etc

Install WMS dependencies

6. Install the Mapnik WMS dependencies if you wish to use the WMS server (Otherwise optional)

  • More details in the WMS Readme in SVN 
    $ wget ftp://xmlsoft.org/libxml2/libxml2-sources-2.6.13.tar.gz
$ tar xvzf libxml2-sources-2.6.13.tar.gz
$ cd libxml2-2.6.13/
$ make
# make install

    $ wget ftp://xmlsoft.org/libxml2/libxslt-1.1.23.tar.gz
$ tar xvf libxslt-1.1.23.tar.gz
$ cd libxslt-1.1.23
$ make
# make install

    # easy_install lxml

    $ tar xzvf Imaging-1.1.6.tar.gz 
$ cd Imaging-1.1.6
# python setup.py install
  • TODO FastCGI/mod_fcgi example installation

Finally, build and install Mapnik

7. Run scons (debug mode flag, DEBUG=y, is recommended for troubleshooting later on) 

$ cd mapnik-0.5.1
$ python scons/scons.py DEBUG=y
  • If the scons build process is not able to find a required dependency it will exit.
    • You'll need to manually set the paths to the locations of library (libs) and/or header files (includes)
    • See the svn INSTALL readme for more details about setting paths or issue the command:
  • You will be looking for an output once scons finds all necessary dependencies (an elusive target) that looks like: 
    $ python scons/scons.py DEBUG=y
scons: Reading SConscript files ...
Building on Darwin ...
pkg-config --exists cairomm-1.0
Checking for C library m...  yes
Checking for C library ltdl...  yes
Checking for C library png...  yes
Checking for C library tiff...  yes
Checking for C library z...  yes
Checking for C library jpeg...  yes
Checking for C library proj...  no
Checking for C library pq...  no
Checking for C++ library icuuc...  yes
Checking for C++ library icudata...  yes
Checking for C++ library gdal...  no
Checking for C++ library boost_filesystem-mt...  yes
Checking for C++ library boost_regex-mt...  yes
Checking for C++ library boost_iostreams-mt...  yes
Checking for C++ library boost_program_options-mt...  yes
Checking for C++ library boost_thread-mt...  yes
Bindings Python version... 2.5
Python 2.5 prefix... /System/Library/Frameworks/Python.framework/Versions/2.5
pkg-config --exists pycairo
scons: done reading SConscript files.
[... build process will commence...]
  • Mapnik should be successfully built at the culmination of that command.
  • If this fails with an error complaining that boost filesystem cannot be found, check the section above for building boost and add the symlinks. Also ensure you add the following to the scons command (assuming built from source and default installation folder) 
    $ python scons/scons.py DEBUG=y BOOST_LIBS=/usr/local/lib BOOST_INCLUDES=/usr/local/includes/boost-1_35/
  • Then you should install the compiled files: 
    $ python scons/scons.py install DEBUG=y

Test Installation

8. Now test your mapnik installation in the python interpreter: 

$ python
>>> import mapnik
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ImportError: No module named mapnik
>>> from mapnik import
  • Whoops, the mapnik module is not on sys.path!
  • This command will show you what is on your PYTHONPATH: 
    $ python
>>> import sys
>>> sys.path
['', '/Library/Python/2.5/site-packages/ ....

9. If you got the ImportError put your mapnik module in your PYTHONPATH like so:

  • Place this text in either /etc/profile or ~/.bash_profile 
    export PYTHONPATH=/usr/lib/python2.5/site-packages/
  • Or Symlink to your Mapnik module from the default site-packages directory (it should be on your path automatically) 
    # ln -s /System/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/site-packages/mapnik /Library/Python/2.5/site-packages/mapnik
  • Find your default site-packages directory like so: 
    $ python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"

10. Now return to the python interpreter: 

$ python
>>> import mapnik
registered datasource : gdal
registered datasource : postgis
registered datasource : raster
registered datasource : shape
>>> dir(mapnik) # This gets you a list of symbols
['BoostPythonMetaclass', 'Color', 'Coord', 'CreateDatasource'
 [.....]
 'scale_denominator', 'setdlopenflags']
>>> help(mapnik)

  • Congrats: you can now head to the Getting Started page for a 'Hello World' demo of using Mapnik via the python bindings.