Updated Using SCons with Mapnik (markdown)

ThomasG77 2011-12-10 09:55:05 -08:00
parent d0467e0c9d
commit 9ca5646d06

@ -24,13 +24,13 @@ For the impatient just do:
* No, for convenience Mapnik bundles a `scons-local` directory that includes all the SCons python modules needed to build Mapnik.. * No, for convenience Mapnik bundles a `scons-local` directory that includes all the SCons python modules needed to build Mapnik..
* This allows you to run scons locally within the Mapnik source folder like: * This allows you to run scons locally within the Mapnik source folder like:
$ python scons/scons.py $ python scons/scons.py
### I already have SCons installed, can I use it? ### I already have SCons installed, can I use it?
* Yes, to use your installed version of SCons rather than the bundled version just run the command: * Yes, to use your installed version of SCons rather than the bundled version just run the command:
$ scons $ scons
### How does SCons compare to `make`? ### How does SCons compare to `make`?
* SCons is less verbose, handles dependency checking more thoroughly, and caches configuration settings differently. * SCons is less verbose, handles dependency checking more thoroughly, and caches configuration settings differently.
@ -99,14 +99,14 @@ For more details on SCons vs other build tools see: http://www.scons.org/wiki/Sc
* SCons accepts command-line `key=value` arguments to customize paths to look for dependecies as well as other valuable options. * SCons accepts command-line `key=value` arguments to customize paths to look for dependecies as well as other valuable options.
* All these arguments take the form of UPPERCASE = lowercase key value pairs. To see all possible options type: * All these arguments take the form of UPPERCASE = lowercase key value pairs. To see all possible options type:
#!sh #!sh
python scons/scons.py -h python scons/scons.py -h
..or if you have set custom configurations and want to see what affect they have had first `configure` then see the help: ..or if you have set custom configurations and want to see what affect they have had first `configure` then see the help:
#!sh #!sh
python scons/scons.py configure SOME_VARIABLE=some_value python scons/scons.py configure SOME_VARIABLE=some_value
python scons/scons.py -h python scons/scons.py -h
* If something goes wrong when finding dependencies make sure to look in the 'config.log' for any suspicious errors when SCons tried to compile the test targets. * If something goes wrong when finding dependencies make sure to look in the 'config.log' for any suspicious errors when SCons tried to compile the test targets.
@ -118,289 +118,287 @@ For more details on SCons vs other build tools see: http://www.scons.org/wiki/Sc
* To get a view of the various customization options specific to building Mapnik run: * To get a view of the various customization options specific to building Mapnik run:
#!sh #!sh
python scons/scons.py -h python scons/scons.py -h
* To see some overall SCons options run: * To see some overall SCons options run:
#!sh #!sh
python scons/scons.py -H python scons/scons.py -H
* If during the `configure` stage Scons aborts because you are missing a dependency it will print the library name or the tool used to find libraries (ie xml2-config). * If during the `configure` stage Scons aborts because you are missing a dependency it will print the library name or the tool used to find libraries (ie xml2-config).
* The first way to attempt to direct SCons to custom paths for your dependencies is to set the 'LIBS' and 'INCLUDES' variables for a given library, for example: * The first way to attempt to direct SCons to custom paths for your dependencies is to set the 'LIBS' and 'INCLUDES' variables for a given library, for example:
#!sh #!sh
python scons/scons.py configure BOOST_INCLUDES=/opt/local/includes/boost BOOST_LIBS=/opt/local/lib python scons/scons.py configure BOOST_INCLUDES=/opt/local/includes/boost BOOST_LIBS=/opt/local/lib
* If the tool used to find a library cannot be found then specify the custom path to the program: * If the tool used to find a library cannot be found then specify the custom path to the program:
#!sh #!sh
python scons/scons.py configure PG_CONFIG=/usr/lib/postgresql/8.3/bin/pg_config XML2_CONFIG=/usr/local/bin/xml2-config python scons/scons.py configure PG_CONFIG=/usr/lib/postgresql/8.3/bin/pg_config XML2_CONFIG=/usr/local/bin/xml2-config
* Building Mapnik in debug mode can be a useful thing for new users or developers as it prompts printing of status output during rendering. * Building Mapnik in debug mode can be a useful thing for new users or developers as it prompts printing of status output during rendering.
* *NOTE*: Debug mode also means that Mapnik compilation is not optimized so Mapnik will run *slower*. * *NOTE*: Debug mode also means that Mapnik compilation is not optimized so Mapnik will run *slower*.
#!sh #!sh
python scons/scons.py configure DEBUG=True python scons/scons.py configure DEBUG=True
* Note: set `XML_DEBUG=True` in addition if you want to see boost spirit debug output during XML parsing. * Note: set `XML_DEBUG=True` in addition if you want to see boost spirit debug output during XML parsing.
* As noted above SCons will inherit variables from a local 'config.py' files but if you don't want this to happen you can do: * As noted above SCons will inherit variables from a local 'config.py' files but if you don't want this to happen you can do:
#!sh #!sh
python scons/scons.py configure USE_CONFIG=False python scons/scons.py configure USE_CONFIG=False
...or you can point SCons at a custom list of locations for python files to inherit variables from: ...or you can point SCons at a custom list of locations for python files to inherit variables from:
#!sh #!sh
python scons/scons.py configure CONFIG=/home/dane/config.py,/opt/mapnik/custom_config.py python scons/scons.py configure CONFIG=/home/dane/config.py,/opt/mapnik/custom_config.py
* *NEW in version 0.6.0* * *NEW in version 0.6.0*
* Libxml2 is now the default XMLPARSER which adds Entities support to Mapnik * Libxml2 is now the default XMLPARSER which adds Entities support to Mapnik
* But you can still configure Mapnik to build against tinyxml or spirit if you like: * But you can still configure Mapnik to build against tinyxml or spirit if you like:
#!sh #!sh
python scons/scons.py configure XML_PARSER=tinyxml python scons/scons.py configure XML_PARSER=tinyxml
* If you are experiencing any build problems it can be helpful to clean out all previous compiled files in the source directory: * If you are experiencing any build problems it can be helpful to clean out all previous compiled files in the source directory:
#!sh #!sh
python scons/scons.py -c python scons/scons.py -c
* Boost can often require extra variables (beyond the standard BOOST_INCLUDES and BOOST_LIBS) for SCons to properly find and link the boost library. * Boost can often require extra variables (beyond the standard BOOST_INCLUDES and BOOST_LIBS) for SCons to properly find and link the boost library.
* This is largely due to the different ways that boost installations create symlinks. * This is largely due to the different ways that boost installations create symlinks.
* Often source installs of boost can be properly found by specifying the BOOST_TOOLKIT or BOOST_VERSION variables: * Often source installs of boost can be properly found by specifying the BOOST_TOOLKIT or BOOST_VERSION variables:
#!sh #!sh
python scons/scons.py configure BOOST_TOOLKIT=gcc43 BOOST_VERSION=1_37 python scons/scons.py configure BOOST_TOOLKIT=gcc43 BOOST_VERSION=1_37
* The PostGIS, Shape, and Raster (TIFF) plugins are attempted to be build by default. To enable the compilation of further plugins either do: * The PostGIS, Shape, and Raster (TIFF) plugins are attempted to be build by default. To enable the compilation of further plugins either do:
#!sh #!sh
python scons/scons.py configure INPUT_PLUGINS=all python scons/scons.py configure INPUT_PLUGINS=all
or.. or..
#!sh #!sh
python scons/scons.py configure INPUT_PLUGINS=postgis,shape,gdal,ogr,sqlite # etc... python scons/scons.py configure INPUT_PLUGINS=postgis,shape,gdal,ogr,sqlite # etc...
* Cairo is an optional dependency that will be built by default if the Cairo and Cairomm (C++ bindings to Cairo) can be found. To disable to default building of Cairo do: * Cairo is an optional dependency that will be built by default if the Cairo and Cairomm (C++ bindings to Cairo) can be found. To disable to default building of Cairo do:
#!sh #!sh
python scons/scons.py configure CAIRO=False python scons/scons.py configure CAIRO=False
* *Note*: if Cairo and Cairomm are found, pycairo will also be built by default to enable the python binding to Cairo (and therefore access to Cairo functions in Mapnik via the Mapnik python bindings). * *Note*: if Cairo and Cairomm are found, pycairo will also be built by default to enable the python binding to Cairo (and therefore access to Cairo functions in Mapnik via the Mapnik python bindings).
* SCons is very good at checking if the source code of any dependencies or the mapnik codes has changed, in order to know what targets to rebuild. This means that SCons builds can start slow. * SCons is very good at checking if the source code of any dependencies or the mapnik codes has changed, in order to know what targets to rebuild. This means that SCons builds can start slow.
* To skip this behavior (only recommended for advanced users) at the cost of accurate builds turn on the FAST option with: * To skip this behavior (only recommended for advanced users) at the cost of accurate builds turn on the FAST option with:
#!sh #!sh
python scons/scons.py configure FAST=True python scons/scons.py configure FAST=True
* If you have a machine with several processors you can run parallel builds to speed up compilation with the JOBS option: * If you have a machine with several processors you can run parallel builds to speed up compilation with the JOBS option:
#!sh #!sh
python scons/scons.py configure JOBS=2 python scons/scons.py configure JOBS=2
* Below is a dump of all the SCons options*
*Below is a dump of all the SCons options*
Note: this is based on a Mac OS 10.5 setup Note: this is based on a Mac OS 10.5 setup
#!sh
$ python scons/scons.py -h
scons: Reading SConscript files ...
#!sh Welcome to Mapnik...
$ python scons/scons.py -h
scons: Reading SConscript files ...
Welcome to Mapnik... scons: done reading SConscript files.
scons: done reading SConscript files. CXX: The C++ compiler to use (defaults to g++).
default: g++
actual: g++
CXX: The C++ compiler to use (defaults to g++). OPTIMIZATION: Set g++ optimization level (0|1|2|3)
default: g++ default: 2
actual: g++ actual: 3
OPTIMIZATION: Set g++ optimization level (0|1|2|3) DEBUG: Compile a debug version of Mapnik (yes|no)
default: 2 default: False
actual: 3 actual: True
DEBUG: Compile a debug version of Mapnik (yes|no) XML_DEBUG: Compile a XML verbose debug version of mapnik (yes|no)
default: False default: False
actual: True actual: False
XML_DEBUG: Compile a XML verbose debug version of mapnik (yes|no) INPUT_PLUGINS: Input drivers to include
default: False (all|none|comma-separated list of names)
actual: False allowed names: raster sqlite postgis ogr shape osm occi gdal
default: raster,postgis,shape
actual: gdal occi ogr osm postgis raster shape sqlite
INPUT_PLUGINS: Input drivers to include CONFIG: The path to the python file in which to save user configuration options. Currently : 'config.py'
(all|none|comma-separated list of names) default: config.py
allowed names: raster sqlite postgis ogr shape osm occi gdal actual: config.py
default: raster,postgis,shape
actual: gdal occi ogr osm postgis raster shape sqlite
CONFIG: The path to the python file in which to save user configuration options. Currently : 'config.py' USE_CONFIG: Use SCons user '%s' file (will also write variables after successful configuration) (yes|no)
default: config.py default: True
actual: config.py actual: True
USE_CONFIG: Use SCons user '%s' file (will also write variables after successful configuration) (yes|no) FAST: Make scons faster at the cost of less precise dependency tracking (yes|no)
default: True default: False
actual: True actual: False
FAST: Make scons faster at the cost of less precise dependency tracking (yes|no) PREFIX: The install path "prefix"
default: False default: /usr/local
actual: False actual: /usr/local
PREFIX: The install path "prefix" PYTHON_PREFIX: Custom install path "prefix" for python bindings (default of no prefix)
default: /usr/local default:
actual: /usr/local actual: /Users/spring/mapnik-python/
PYTHON_PREFIX: Custom install path "prefix" for python bindings (default of no prefix) DESTDIR: The root directory to install into. Useful mainly for binary package building
default: default: /
actual: /Users/spring/mapnik-python/ actual: /
DESTDIR: The root directory to install into. Useful mainly for binary package building BOOST_INCLUDES: Search path for boost include files ( /path/to/BOOST_INCLUDES )
default: / default: /usr/include
actual: / actual: /usr/include
BOOST_INCLUDES: Search path for boost include files ( /path/to/BOOST_INCLUDES ) BOOST_LIBS: Search path for boost library files ( /path/to/BOOST_LIBS )
default: /usr/include default: /usr/lib
actual: /usr/include actual: /usr/lib
BOOST_LIBS: Search path for boost library files ( /path/to/BOOST_LIBS ) BOOST_TOOLKIT: Specify boost toolkit, e.g., gcc41.
default: /usr/lib default:
actual: /usr/lib actual:
BOOST_TOOLKIT: Specify boost toolkit, e.g., gcc41. BOOST_ABI: Specify boost ABI, e.g., d.
default: default:
actual: actual:
BOOST_ABI: Specify boost ABI, e.g., d. BOOST_VERSION: Specify boost version, e.g., 1_35.
default: default:
actual: actual:
BOOST_VERSION: Specify boost version, e.g., 1_35. FREETYPE_CONFIG: The path to the freetype-config executable.
default: default: freetype-config
actual: actual: freetype-config
FREETYPE_CONFIG: The path to the freetype-config executable. XML2_CONFIG: The path to the xml2-config executable.
default: freetype-config default: xml2-config
actual: freetype-config actual: xml2-config
XML2_CONFIG: The path to the xml2-config executable. ICU_INCLUDES: Search path for ICU include files ( /path/to/ICU_INCLUDES )
default: xml2-config default: /usr/include
actual: xml2-config actual: /usr/include
ICU_INCLUDES: Search path for ICU include files ( /path/to/ICU_INCLUDES ) ICU_LIBS: Search path for ICU include files ( /path/to/ICU_LIBS )
default: /usr/include default: /usr/lib
actual: /usr/include actual: /usr/lib
ICU_LIBS: Search path for ICU include files ( /path/to/ICU_LIBS ) PNG_INCLUDES: Search path for libpng include files ( /path/to/PNG_INCLUDES )
default: /usr/lib default: /usr/include
actual: /usr/lib actual: /usr/include
PNG_INCLUDES: Search path for libpng include files ( /path/to/PNG_INCLUDES ) PNG_LIBS: Search path for libpng include files ( /path/to/PNG_LIBS )
default: /usr/include default: /usr/lib
actual: /usr/include actual: /usr/lib
PNG_LIBS: Search path for libpng include files ( /path/to/PNG_LIBS ) JPEG_INCLUDES: Search path for libjpeg include files ( /path/to/JPEG_INCLUDES )
default: /usr/lib default: /usr/include
actual: /usr/lib actual: /usr/include
JPEG_INCLUDES: Search path for libjpeg include files ( /path/to/JPEG_INCLUDES ) JPEG_LIBS: Search path for libjpeg library files ( /path/to/JPEG_LIBS )
default: /usr/include default: /usr/lib
actual: /usr/include actual: /usr/lib
JPEG_LIBS: Search path for libjpeg library files ( /path/to/JPEG_LIBS ) TIFF_INCLUDES: Search path for libtiff include files ( /path/to/TIFF_INCLUDES )
default: /usr/lib default: /usr/include
actual: /usr/lib actual: /usr/include
TIFF_INCLUDES: Search path for libtiff include files ( /path/to/TIFF_INCLUDES ) TIFF_LIBS: Search path for libtiff library files ( /path/to/TIFF_LIBS )
default: /usr/include default: /usr/lib
actual: /usr/include actual: /usr/lib
TIFF_LIBS: Search path for libtiff library files ( /path/to/TIFF_LIBS ) PROJ_INCLUDES: Search path for PROJ.4 include files ( /path/to/PROJ_INCLUDES )
default: /usr/lib default: /usr/local/include
actual: /usr/lib actual: /usr/local/include
PROJ_INCLUDES: Search path for PROJ.4 include files ( /path/to/PROJ_INCLUDES ) PROJ_LIBS: Search path for PROJ.4 library files ( /path/to/PROJ_LIBS )
default: /usr/local/include default: /usr/local/lib
actual: /usr/local/include actual: /usr/local/lib
PROJ_LIBS: Search path for PROJ.4 library files ( /path/to/PROJ_LIBS ) INTERNAL_LIBAGG: Use provided libagg (yes|no)
default: /usr/local/lib default: True
actual: /usr/local/lib actual: True
INTERNAL_LIBAGG: Use provided libagg (yes|no) CAIRO: Attempt to build with Cairo rendering support (yes|no)
default: True default: True
actual: True actual: True
CAIRO: Attempt to build with Cairo rendering support (yes|no) GDAL_CONFIG: The path to the gdal-config executable for finding gdal and ogr details.
default: True default: gdal-config
actual: True actual: gdal-config
GDAL_CONFIG: The path to the gdal-config executable for finding gdal and ogr details. PG_CONFIG: The path to the pg_config executable.
default: gdal-config default: pg_config
actual: gdal-config actual: pg_config
PG_CONFIG: The path to the pg_config executable. OCCI_INCLUDES: Search path for OCCI include files ( /path/to/OCCI_INCLUDES )
default: pg_config default: /usr/lib/oracle/10.2.0.3/client/include
actual: pg_config actual: /usr/lib/oracle/10.2.0.3/client/include
OCCI_INCLUDES: Search path for OCCI include files ( /path/to/OCCI_INCLUDES ) OCCI_LIBS: Search path for OCCI library files ( /path/to/OCCI_LIBS )
default: /usr/lib/oracle/10.2.0.3/client/include default: /usr/lib/oracle/10.2.0.3/client/lib
actual: /usr/lib/oracle/10.2.0.3/client/include actual: /usr/lib/oracle/10.2.0.3/client/lib
OCCI_LIBS: Search path for OCCI library files ( /path/to/OCCI_LIBS ) SQLITE_INCLUDES: Search path for SQLITE include files ( /path/to/SQLITE_INCLUDES )
default: /usr/lib/oracle/10.2.0.3/client/lib default: /usr/include/
actual: /usr/lib/oracle/10.2.0.3/client/lib actual: /usr/local/include
SQLITE_INCLUDES: Search path for SQLITE include files ( /path/to/SQLITE_INCLUDES ) SQLITE_LIBS: Search path for SQLITE library files ( /path/to/SQLITE_LIBS )
default: /usr/include/ default: /usr/lib
actual: /usr/local/include actual: /usr/local/lib
SQLITE_LIBS: Search path for SQLITE library files ( /path/to/SQLITE_LIBS ) SYSTEM_FONTS: Provide location for python bindings to register fonts (if given aborts installation of bundled DejaVu fonts)
default: /usr/lib default:
actual: /usr/local/lib actual:
SYSTEM_FONTS: Provide location for python bindings to register fonts (if given aborts installation of bundled DejaVu fonts) LIB_DIR_NAME: Name to use for lib folder where fonts and plugins are installed
default: default: /mapnik/
actual: actual: /mapnik/
LIB_DIR_NAME: Name to use for lib folder where fonts and plugins are installed PYTHON: Full path to Python executable used to build bindings ( /path/to/PYTHON )
default: /mapnik/ default: /System/Library/Frameworks/Python.framework/Versions/2.5/Resources/Python.app/Contents/MacOS/Python
actual: /mapnik/ actual: /System/Library/Frameworks/Python.framework/Versions/2.5/Resources/Python.app/Contents/MacOS/Python
PYTHON: Full path to Python executable used to build bindings ( /path/to/PYTHON ) FRAMEWORK_PYTHON: Link against Framework Python on Mac OSX (yes|no)
default: /System/Library/Frameworks/Python.framework/Versions/2.5/Resources/Python.app/Contents/MacOS/Python default: True
actual: /System/Library/Frameworks/Python.framework/Versions/2.5/Resources/Python.app/Contents/MacOS/Python actual: True
FRAMEWORK_PYTHON: Link against Framework Python on Mac OSX (yes|no) BINDINGS: Language bindings to build
default: True (all|none|comma-separated list of names)
actual: True allowed names: python
default: all
actual: python
BINDINGS: Language bindings to build THREADING: Set threading support (multi|single)
(all|none|comma-separated list of names) default: multi
allowed names: python actual: multi
default: all
actual: python
THREADING: Set threading support (multi|single) XMLPARSER: Set xml parser (tinyxml|spirit|libxml2)
default: multi default: libxml2
actual: multi actual: libxml2
XMLPARSER: Set xml parser (tinyxml|spirit|libxml2) JOBS: Set the number of parallel compilations
default: libxml2 default: 1
actual: libxml2 actual: 4
JOBS: Set the number of parallel compilations DEMO: Compile demo c++ application (yes|no)
default: 1 default: False
actual: 4 actual: False
DEMO: Compile demo c++ application (yes|no) PGSQL2SQLITE: Compile and install a utility to convert postgres tables to sqlite (yes|no)
default: False default: False
actual: False actual: True
PGSQL2SQLITE: Compile and install a utility to convert postgres tables to sqlite (yes|no) Use scons -H for help about command-line options.
default: False
actual: True
Use scons -H for help about command-line options.