D 2014-06-25T17:03:02.597 L mod_spatialite U sandro W 5308 back to 4.2.0-doc

Dynamically loading SpatiaLite as an extension module

Theoretical foundations

Speacking in rigorous technical terms, SpatiaLite simply is an extension to SQLite.
Consequently we are strictly required to deploy some appropriate mechanism allowing to load both binary libraries (libsqlite3 and libspatialite) and properly registering within SQLite3 the many extended Spatial SQL functions implemented by SpatiaLite.
A further compication should be taken in proper debt; libspatialite isn't a stand-alone self-contained library, and depends on several further libraries (libgeos, libproj, libxml2 and so on).

There are several possible alternative paths leading to this final goal:

using static linkage: a straighforward solution avoiding many subsequent headhaches related to installation and run-time configuration.
Following this approach a single monolithic fat executable internally containing all required binary code will be created at build time; this monolithic executable will have no external dependencies at all, thus radically simplifying any installation task.
Such strategy nicely works in the case of stand-alone self-contained apps (e.g. both spatialite.exe and spatialite_gui.exe Windows binaries are usually built this way).
Unhappily this elementary simple solution doesn't fit well in Linux and Unix-like environments; and even worst often directly conflicts with the internal architecture supported by many language connectors.
using shared libraries (aka DLLs on Windows).
This second approach will carefully avoid to link alltogether a monolithic executable; each single code component will be shipped as an autonomous individual member, and only at run-time all component will be finally bound together.
The good new is that this way each library will be (hopefully) installed only once on your system, and that every executable depending on that library will load exactly the same binary code, thus granting a robust consistency.
The bad new is in that if a single required component couldn't be loaded at run-time (for any possible reason) the executable as a whole will fail to run.
To make things even worst, this schema works nicely on Linux, Unix and Mac OS X (because all these o.s. adopts strong rules intended to enforce overall system robustness); but on Windows it's not at all difficult to create the infamous DLL hell, simply because this o.s. substantially hasn't strong rules to be respected, thus vanishing any possible system consistency.

using real dynamic linkage (which isn't the same of simply using shared libraries).
Following this third approach an extension module could be selectively loaded or not; if for any reason the main executable fails to load an eventual extension module, it will still continue to work (obviously missing to support the failing extension).
Happily enough SQLite3 fully supports this third more sophisticated mechanism; and this option is widely supported by many language connectors.

How it works
libsqlite3 has the capability to dynamically load extension modules. This feature is available as a C-language API, but is avaibles as a special SQL function as well: SELECT load_extension('mod_spatialite'); This SQL function make elementary simple (and language independent) the problem of loading any possible extension; you are simply expected to execute a rather trivial SQL statement in order to load an external extension.

Loadable extension anathomy:

any SQLite extension module is expected to declare a conventional interface.
Except for this, any SQLite's own extension simply is an ordinary shared library or DLL as any other.

if such interface isn't correctly declared by the shared library being loaded, then SQLite3 will simply assume that it's not a valid extension module.
And consequently will refuse to load the module without any other consequence (except may be printing some appropriate error message).

a more obvious failure cause could be the one to attempt loading a not existing module (or possibly, a module whom actual address couldn't be resolved following the standard seach rules).

finally, the module could effectively exists and could correctly declare a valid conventional interface. Anyway, if the corresponding shared library has further dependecies some broken link could possibly forbid a succesful loading.

the last hill-fated combination: SQLite3 is a strongly configurable component. If for any highly opinable choice your system packages had decided to disable at all the extension module mechamism you'll then never be able to load any extension. Full stop. (anyway you'll probably be able to switch to some more reasoble / less paranoid distribution).

back to 4.2.0-doc Z 8b2e823048b8ecede253987fe6050ada