diff --git a/INSTALL.md b/INSTALL.md index 19fe1ff29..f3b715d48 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,19 +1,27 @@ # Mapnik Installation +Mapnik is cross platform and runs on Linux, Mac OSX, Solaris, *BSD, and Windows. -## Quick Start - -To configure and build mapnik do: +To configure and build Mapnik do: ./configure make + +NOTE: the above will not work on windows, rather see https://github.com/mapnik/mapnik/wiki/BuildingOnWindows + +Then to run the tests locally (without needing to install): + + make test-local + +Install like: + sudo make install If you need to uninstall do: sudo make uninstall -For more details see the 'Building' Section below. +For more details see the `Building` Section below. Platform specific install guides at https://github.com/mapnik/mapnik/wiki/Mapnik-Installation @@ -22,58 +30,54 @@ For troubleshooting help see https://github.com/mapnik/mapnik/wiki/InstallationT ## Depends -Mapnik is cross platform and runs on Linux, Mac OSX, Solaris, *BSD, and Windows. - -The build system should work for all posix/unix systems but for windows see: - - https://github.com/mapnik/mapnik/wiki/BuildingOnWindows - -Build dependencies are: +Build system dependencies are: * C++ compiler (like g++ or clang++) - * Python >= 2.4 * >= 2 GB RAM + * Python 2.4-2.7 + * Scons (a copy is bundled) Mapnik Core depends on: * Boost - >= 1.47 is required. - - These libraries are required: + - These libraries are used: - filesystem - system - thread (if mapnik threadsafe support is required, default on) - regex (optionally built with icu regex support) - program_options (optionally for mapnik command line programs) - * libicuuc >= 4.0 (ideally >= 4.2) - International Components for Unicode - * libpng >= 1.2.x - PNG Graphics - * libjpeg - JPEG Graphics - * libtiff - TIFF Graphics - * libz - Zlib Compression - * libfreetype - Freetype2 for Font support (Install requires freetype-config) + * libpng >= 1.2.x - PNG graphics + * libjpeg - JPEG graphics + * libtiff - TIFF graphics + * libz - Zlib compression + * libfreetype - Freetype2 for font support (Install requires freetype-config) * libxml2 - XML parsing (Install requires xml2-config) - * libproj - PROJ.4 Projection library + * libproj - PROJ.4 projection library -Mapnik Python binding depend on: +Mapnik Python bindings depend on: - * Python >= 2.4 + * Python 2.5-2.7 or >= 3.2 * Boost python +Note: Python3k is supported, see: https://github.com/mapnik/mapnik/wiki/Python3k + Optional dependencies: - * Cairo - Graphics library for PDF, PS, and SVG formats + * Cairo - Graphics library for output formats like PDF, PS, and SVG - pkg-config - Required for building with cairo support - 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) + * libsqlite3 - SQLite input (needs RTree support builtin) (sqlite plugin support) * libocci - Oracle input plugin support * libcurl - OSM input plugin support Instructions for installing many of these dependencies on -various platforms can be found at the Mapnik Community Wiki -(https://github.com/mapnik/mapnik/wiki/Mapnik-Installation). +various platforms can be found at the Mapnik Wiki: +https://github.com/mapnik/mapnik/wiki/Mapnik-Installation ## Building @@ -84,6 +88,10 @@ We provide a simple Makefile wrapper that can be used like: ./configure && make && make install +For help on what options are accepted do: + + ./configure --help + To interact with the local copy of scons directly you can do: python scons/scons.py configure @@ -96,9 +104,9 @@ If you want to clean your build do: make clean -If you experience odd configure errors, try resetting the SCons caches: +If you experience odd configure errors, try cleaning the configure caches: - make reset + make distclean To install in a custom location do: @@ -116,57 +124,50 @@ To pass custom paths to a dependency, like icu, do: ./configure ICU_INCLUDES=/usr/local/include ICU_LIBS=/usr/local/include -If you want to see configure options do: - - ./configure --help - -For more details on all the options see: +For more details on usage see: https://github.com/mapnik/mapnik/wiki/UsingScons ## Testing Installation -First, try importing the Mapnik python module in a python interpreter, -and make sure it does so without errors: +You can run the Mapnik tests locally (without installing) like: - $ 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 - >>> + make test-local # see the Makefile for how this works -Then, try rendering the demo map, included in the Mapnik source code:: +Or you can install and test like: - cd demo/python - python rundemo.py + make install && make test -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. +Many of the tests are written in python and you can run them individually like: -For further tests see the `tests` folder within the Mapnik source code. + make install + python tests/python_tests/shapefile_test.py ## Learning Mapnik -### Users +### Help -Visit https://github.com/mapnik/mapnik/wiki/LearningMapnik for basic tutorials on making maps with Mapnik using the Python bindings. +Mapnik has an active community of talented users and developers making beautiful maps. -### Developers +If you need help or want to participate starting points include: + +- Sign up and post to the mailing list: http://mapnik.org/contact/ +- Join and ask questions on the #mapnik channel on irc://irc.freenode.net/mapnik +- Add your help questions to https://github.com/mapnik/mapnik-support + +### Cartographers + +TileMill, which uses Mapnik internally, offers great step by step tutorials for +learning advanced map styling: http://mapbox.com/tilemill/docs/crashcourse/introduction/ + +### Programmers + +Mapnik is great for building your own mapping applications. Visit +https://github.com/mapnik/mapnik/wiki/LearningMapnik for basic +tutorials on how to programmatically use Mapnik. + +### Contributers Read docs/contributing.markdown for resources for getting involved with Mapnik development. - - -## Mapnik Community - - -Mapnik has an active community of talented users and developers making -amazing maps. - -Please feel free to subscribe to the community list and post on both -usage and development topics: http://mapnik.org/contact/ - -You can also get involved by joining the #mapnik channel on irc://irc.freenode.net/mapnik