install guide: add scons build dep, make note of py3k issues, and overall cleanup. closes #1692

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.
+Build system dependencies are:
-
-The build system should work for all posix/unix systems but for windows see:
-
-    https://github.com/mapnik/mapnik/wiki/BuildingOnWindows
-
-Build 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
+ * libpng >= 1.2.x - PNG graphics
- * libjpeg - JPEG Graphics
+ * libjpeg - JPEG graphics
- * libtiff - TIFF Graphics 
+ * libtiff - TIFF graphics 
- * libz - Zlib Compression
+ * libz - Zlib compression
- * libfreetype - Freetype2 for Font support (Install requires freetype-config)
+ * 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
+various platforms can be found at the Mapnik Wiki:
-(https://github.com/mapnik/mapnik/wiki/Mapnik-Installation).
 
+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:
+For more details on usage see:
-
-    ./configure --help
-
-For more details on all the options see:
 
     https://github.com/mapnik/mapnik/wiki/UsingScons
 
 
 ## Testing Installation
 
-First, try importing the Mapnik python module in a python interpreter,
+You can run the Mapnik tests locally (without installing) like:
-and make sure it does so without errors:
 
-    $ python
+    make test-local # see the Makefile for how this works
-    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::
+Or you can install and test like:
 
-    cd demo/python
+    make install && make test
-    python rundemo.py 
 
-If the resulting maps look good, this indicates the core components of
+Many of the tests are written in python and you can run them individually like:
-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.
+    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