Updated InstallationTroubleshooting (markdown)

InstallationTroubleshooting.md

@@ -49,10 +49,11 @@
         /usr/local/include/boost/python/numeric.hpp:121: instantiated from ‘void boost::python::numeric::array::resize(const Sequence&) [with Sequence = boost::python::tuple]’ /usr/local/include/boost/preprocessor/iteration/detail/local.hpp: 37: instantiated from here /usr/local/include/boost/python/object_core.hpp:330: error: ‘object_base_initializer’ was not declared in this scope
         scons: *** [bindings/python/mapnik_shield_symbolizer.os] Error 1
         scons: building terminated because of errors.
+
  * *Solution*: You need to re-compile boost_python, correctly. Likely what is happening is that you have multiple python versions on your system, and when you built boost, the boost_python library compiled against a different set of headers than it linked against. Basically, `bjam`, the tool used to build boost, is not very smart about linking to python versions, and needs extra help. At the least you MUST pass the python version to `bjam` like:
 
-
         bjam --with-python python=2.6 [...snip...]
+
  * And sometimes even that does not work. *HINT:* pass the `-d2` flag to see all the compile commands sent to `gcc` by `bjam` and you will likely see something like `-I/usr/include/python24` in the compile arguments when it should be `-I/usr/include/python26` (or some older version of python headers). If this happens then you can craft a full config file (with all possible python info) and pass a reference to that on the bjam command line. Docs on this are here: http://www.boost.org/doc/libs/1_42_0/libs/python/doc/building.html#configuring-boost-build, and an example follows:
 
 Create a file called 'user-config.jam' (but change the python versions to be appropriate):
@@ -85,6 +86,7 @@ Then, go recompile (just boost_python) and move the new library into place:
         #!sh
         Checking for C++ library X... no (cached)
         Could not find header or shared library for X, exiting!
+
  * *Solution*: Use the Scons option `--config=force` which will force Scons to forget about the old location used and honor your new command line variable/options.
 
 ### All boost libs are found except for boost_thread
@@ -94,6 +96,7 @@ Then, go recompile (just boost_python) and move the new library into place:
         Checking for C++ library boost_program_options-mt... yes
         Checking for C++ library boost_thread-mt... no
         Could not find required header or shared library for boost thread
+
  * *Solution*: Likely do to hitting ctrl-c or otherwise aborting the configure stage, SCons internal `.sconf_temp/` have been messed up. Delete them and rebuild:
 
         #!sh
@@ -106,6 +109,7 @@ Then, go recompile (just boost_python) and move the new library into place:
           "boost::re_detail::icu_regex_traits_implementation::do_transform(int const*, int const*, icu::Collator const*) const", referenced from:
           unsigned short const* boost::re_detail::re_is_set_member<unsigned short const*, int, boost::icu_regex_traits, unsigned long long>(unsigned short const*, unsigned short const*, boost::re_detail::re_set_long<unsigned long long> const*, boost::re_detail::regex_data<int, boost::icu_regex_traits> const&, bool)in agg_renderer.os
           unsigned short const* boost::re_detail::re_is_set_member<unsigned short const*, int, boost::icu_regex_traits, unsigned long long>(unsigned short const*, unsigned short const*, boost::re_detail::re_set_long<unsigned long long> const*, boost::re_detail::regex_data<int, boost::icu_regex_traits> const&, bool)in agg_renderer.os
+
  * *Solution*: Likely, your boost library was built without regex+icu support. If you have built libboost from source, you can make your system's relevant .so files be recompiled with that support and reinstalled in place in the /lib/ folders. Go to libboost's source folder and run the following command (which you can find on [latest release install details](http://trac.mapnik.org/wiki/Mapnik2#fromlatestrelease|Mapnik2's)):
 
         #!sh
@@ -187,7 +191,7 @@ Note: If the SCons build process simply can't find an include or library and you
           File "/usr/lib/python2.4/site-packages/mapnik/__init__.py", line 31, in ?
             from _mapnik import *
         ImportError: /usr/local/lib/libmapnik.so.0.5: undefined symbol: _ZN5boost10filesystem6detail15not_found_errorE
-    >>
+    
  * *Solution*: This problem is old and likely fixed now whatever libboost source or recent package you'd take. According to [page](http://lists.boost.org/Archives/boost/2008/03/134329.php|this), the problem was fixed from libboost v1.35. _Rebuild boost and then mapnik. If this does not fix the problem, confirm that your Boost version is compatible with the Mapnik release version, see: BoostCompatibility._ 
 
 *Related to regex symbols with ICU support*
@@ -216,7 +220,8 @@ You may need to run "sudo ldconfig" after that command, then retry "import mapni
         dlopen(/usr/local/lib/mapnik/input/postgis.input, 9): Library not loaded: /opt/local/lib/libboost_thread-mt-1_35.dylib
           Referenced from: /usr/local/lib/mapnik/input/postgis.input
           Reason: image not found
-    # or
+    or
+
         >>> import mapnik
         dlopen(/usr/local/lib/mapnik/input/gdal.input, 9): Library not loaded: /opt/local/lib/libboost_thread-mt-1_35.dylib
           Referenced from: /usr/local/lib/mapnik/input/gdal.input
@@ -246,12 +251,6 @@ You may need to run "sudo ldconfig" after that command, then retry "import mapni
 
  * *Solution*: Mapnik with Cairo needs the following libraries: libcairo2 libcairo2-dev python-cairo python-cairo-dev libcairomm-1.0-1 libcairomm-1.0-dev
 
-
-
-
-
-
-
 ## Linking Errors
 
 ### The libmapnik shared library is not found
@@ -276,7 +275,7 @@ Do the same as above but you'll just need to add an entry of '/usr/local/lib64'
 
 ## Install Errors
 
-=== Permission Denied Error === 
+### Permission Denied Error
 
  * *Description*: Installing mapnik libs requires root priveleges
 
@@ -309,7 +308,6 @@ Do the same as above but you'll just need to add an entry of '/usr/local/lib64'
 
  * Since the Mapnik python bindings use boost python, both boost python (when it is compiled), and mapnik python must be linked against the same version of Python.
 
-
         #!python
         $ python
         Python 2.5 (r25:51918, Sep 19 2006, 08:49:13) 
@@ -332,13 +330,12 @@ Do the same as above but you'll just need to add an entry of '/usr/local/lib64'
 
         $ python scons/scons.py FRAMEWORK_SEARCH_PATH=/Library/Frameworks
 
- * Also see this discussion: MacPythonUpgradeIssues
+ * Also see this discussion: [MacPythonUpgradeIssues](https://github.com/mapnik/mapnik/wiki/MacPythonUpgradeIssues)
 
 ### unknown required load command
 
  * *Description*: You installed mapnik on osx using a binary installer. When you import the Mapnik python bindings you get a generic 'no suitable image found'.
 
-
         >>> import mapnik
         Traceback (most recent call last):
           File "<stdin>", line 1, in <module>
@@ -365,7 +362,6 @@ Do the same as above but you'll just need to add an entry of '/usr/local/lib64'
 
  * *Solution*: This indicates a problem in compiling against mapnik headers. It might be able to be fixed simply by completely cleaning and rebuilding the C++ program that is linking to mapnik. If that does not solve it then this indicates that key compiler flags that affect how inlining are done were likely missing from the compile commands for the program that is building against mapnik headers. You should be using the `mapnik-config --cflags` output when compiling c++ programs against mapnik to ensure that key flags like these are included (but these may change between mapnik releases to check `mapnik-config`):
 
-
         -ansi -Wall -ftemplate-depth-200 -DBOOST_SPIRIT_THREADSAFE -DMAPNIK_THREADSAFE -O3 -finline-functions -Wno-inline -DNDEBUG
 
 ### Proj_init_error