Build system
Please note well: the build system has been heavily modified.
If you are a developer or a system packager you must absolutely read this note very carefully.
- ./configure now will test if any required header file and library is already installed:
in case of failure it now stops reporting the missing component.
- ./configure will build both static and dynamic/shared librarirs: exactly as before
- ./configure now will only build dynamically linked executables
- if your goal is building statically linked executables instead, you must now use the appropriate Makefile
(Makefile-static-MinGW, Makefile-static-Linux and Makefile-static-MacOsX) you'll find into the source's distribution.
Please note: may well be that on some specific platform you must manually hack the Makefile by yourself
|
building libspatialite
- the first important step is choosing between the canonical and the amalgamation distibutions:
- both them shares exactly the same identical base-code
- the canonical distribution completely depends on the external (system) libsqlite3:
and this practically means that if your own system doesn't supports a decently recent SQLite,
or if this one is released with the infamous disable load extensions option,
you'll then be absolutely unable to build and/or deploy libspatialite
- on the other side the amalgamation distribution contains an internal private copy of SQLite 3.7.3:
and this practically means that you'll be able for sure to get a working libspatialite.
- none of them is better or superior to the other:
it all depends on your very specific requirements and system constraints.
Just as a quick rule-of-the-thumb:
- Are you a Linux developer or system packager ?
don't think twice about this, use the canonical libspatialite
- Your main goal is developing stand-alone apps for Windows ?
all right, use the amalgamation libspatialite
- for both versions the following ./configure options are supported:
- --disable-mathsql
this will disable SQL functions such as: Cos(), Sin(), Avg(), ...
not too much useful ...
- --disable-geos
this will completely disable SQL function as: ST_Area(), ST_Difference(), ST_Buffer(), ...
and will effectively remove any dependency from the GEOS library
- --disable-proj
this will completely disable SQL functions as: Transform(), AsKML(), ...
and will effectively remove any dependency from the PROJ.4 library
- --disable-iconv
this will completely disable the VirtualShape, VirtualDbf and VirtualText modules
and will effectively remove any dependency from the ICONV library
- --disable-epsg
this will partially disable the in-coded EPSG dataset: simply the very basic definitions
for the WGS84 and WGS84/UTM projections will be retained
but this is enough to subtract more than 3 MB to libspatialite's allocation size
- --disable-geocallbacks
this will completely disable any support for Geometry Callback functions.
This feature absolutely requires the latest SQLite v.3.7.3
So it's very alike that you'll be absolutely forced to disable geocallbacks in order to
complete a succesfull build if your own libsqlite3 is (slightly) outdated.
- Disabling every option will produce just a minimal sized library. You'll miss for sure lots and
lots of usefull features, but still preserving an untouched bare OGC core.
As a side effect, sacrificing any external dependency make much more easy porting libspatialite to mobile
devices (smartphones and alike)
|
building spatialite-tools
simply invoke ./configure |
building spatialite_gui
simply invoke ./configure |
commonly used ENVIRONMENT settings:
on Linux usually you can fully rely upon default settings: there is no need at all to set any specific variable
on the other side on Mac Os X you must always set the following variables:
export "CFLAGS=-I/opt/local/include"
export "LDFLAGS=-L/opt/local/lib"
this is because you must use several MacPorts packages (sqlite3, geos, libpng, libjpeg,
tiff, proj, libgeotiff, wxwidgets, cairo ...)
and using MacPorts packeages requires the above settings in to make to be visible for ./configure
that's not all: usually libspatialite will be installed on /usr/local/lib: accordingly to this,
you must explicitly set:
export "PKG_CONFING_PATH=/usr/local/lib/pkgconfig"
this is required in order to allow pkg-config able to retrieve the configuration for your libspatialite
more or less the same is required on Windows MinGW/MSYS; in this case you must set:
export "CFLAGS=-I/usr/local/include"
export "LDFLAGS=-L/usr/local/lib"
and
export "PKG_CONFING_PATH=/usr/local/lib/pkgconfig"
Please note well: that's not enough for libspatialite and libgaiagraphics;
for these packages you must also set:
./configure --target=mingw32
|
common pitfalls:
Incorrectly using the amalgamation and canonical distributions will produce odd errors.
This is because you must select once for all your preferred distribution, then maintining a reasonable coherence,
and declaring as appropriate your build options.
Every time your build fails during the link phase, generating lots of complaint about unresolved
sqlite3_.. or SPLite3_.. symbols, for sure you have to deal with a mismatching
distribution problem.
Few basic rules to undestrand:
- the amalgamation and canonical distributions are exactly the same.
- the only difference is that amalgamation includes an internal private copy of SQLite
Accordingly to the above consideration, any C source will then take care to include the corresponding header file:
- #include <sqlite3.h>
in the case of canonical distribution (because you are using the system-wide libsqlite3)
- #include <spatialite/sqlite3.h>
in the case of amalgamation distribution (because you are using the internal private SQLite's copy)
Quite obviously, any mismatch between the header and the library will cause some fatal crash before or later.
So, in order to avoid any risk, the SQLite's internal private copy shipped within the amalgamation
silently renames any SQLite export symbol
[any sqlite3_... symbol is actually remapped to SPLite3_...]
But in order to apply such silent mapping, you must obviously include the corresponding header file.
Anyway writing robust code is absolutely simple and easy: you simply have to define a conditional macro:
#ifdef SPATIALITE_AMALGAMATION
#include <spatialite/sqlite3.h>
#else
#include <sqlite3.h>
#endif
and at compile time you'll then set the amalgamation flag as appropriate:
gcc mysrc.c -o mysrc -lspatialite
if you intend to use the canonical libspatialite
gcc -DSPATIALITE_AMALGAMATION=1 mysrc.c -o mysrc -lspatialite
if you intend to use the amalgamation libspatialite
Anyway this process can be even simpler: this is because libspatialite fully supports pkg-config
So in order to automatically get the correct libspatialite installed on your own system, you simply have to invoke:
gcc mysrc.c -o mysrc $(pkg-config --cflags --libs spatialite)
|