mirror of https://github.com/django/django.git
Separated GIS installation docs in sections
This commit is contained in:
Claude Paroz
parent
7a908747a5
commit
3084b1cfd6
|
|
@ -15,7 +15,7 @@ of spatially enabled data.
|
|||
:maxdepth: 2
|
||||
|
||||
tutorial
|
||||
install
|
||||
install/index
|
||||
model-api
|
||||
db-api
|
||||
geoquerysets
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,282 @@
|
|||
.. _geospatial_libs:
|
||||
|
||||
===============================
|
||||
Installing Geospatial libraries
|
||||
===============================
|
||||
|
||||
GeoDjango uses and/or provides interfaces for the following open source
|
||||
geospatial libraries:
|
||||
|
||||
======================== ==================================== ================================ ==========================
|
||||
Program Description Required Supported Versions
|
||||
======================== ==================================== ================================ ==========================
|
||||
:ref:`GEOS <ref-geos>` Geometry Engine Open Source Yes 3.3, 3.2, 3.1, 3.0
|
||||
`PROJ.4`_ Cartographic Projections library Yes (PostgreSQL and SQLite only) 4.8, 4.7, 4.6, 4.5, 4.4
|
||||
:ref:`GDAL <ref-gdal>` Geospatial Data Abstraction Library No (but, required for SQLite) 1.9, 1.8, 1.7, 1.6, 1.5
|
||||
:ref:`GeoIP <ref-geoip>` IP-based geolocation library No 1.4
|
||||
`PostGIS`__ Spatial extensions for PostgreSQL Yes (PostgreSQL only) 2.0, 1.5, 1.4, 1.3
|
||||
`SpatiaLite`__ Spatial extensions for SQLite Yes (SQLite only) 3.0, 2.4, 2.3
|
||||
======================== ==================================== ================================ ==========================
|
||||
|
||||
.. admonition:: Install GDAL
|
||||
|
||||
While :ref:`gdalbuild` is technically not required, it is *recommended*.
|
||||
Important features of GeoDjango (including the :ref:`ref-layermapping`,
|
||||
geometry reprojection, and the geographic admin) depend on its
|
||||
functionality.
|
||||
|
||||
.. note::
|
||||
|
||||
The GeoDjango interfaces to GEOS, GDAL, and GeoIP may be used
|
||||
independently of Django. In other words, no database or settings file
|
||||
required -- just import them as normal from :mod:`django.contrib.gis`.
|
||||
|
||||
.. _PROJ.4: http://trac.osgeo.org/proj/
|
||||
__ http://postgis.refractions.net/
|
||||
__ http://www.gaia-gis.it/gaia-sins/
|
||||
|
||||
|
||||
On Debian/Ubuntu, you are advised to install the following packages which will
|
||||
install, directly or by dependency, the required geospatial libraries:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ sudo apt-get install binutils libproj-dev gdal-bin
|
||||
|
||||
Optional packages to consider:
|
||||
|
||||
* ``libgeoip1``: for :ref:`GeoIP <ref-geoip>` support
|
||||
* ``gdal-bin``: for GDAL command line programs like ``ogr2ogr``
|
||||
* ``python-gdal`` for GDAL's own Python bindings -- includes interfaces for raster manipulation
|
||||
|
||||
Please also consult platform-specific instructions if you are on :ref:`macosx`
|
||||
or :ref:`windows`.
|
||||
|
||||
.. _build_from_source:
|
||||
|
||||
Building from source
|
||||
====================
|
||||
|
||||
When installing from source on UNIX and GNU/Linux systems, please follow
|
||||
the installation instructions carefully, and install the libraries in the
|
||||
given order. If using MySQL or Oracle as the spatial database, only GEOS
|
||||
is required.
|
||||
|
||||
.. note::
|
||||
|
||||
On Linux platforms, it may be necessary to run the ``ldconfig``
|
||||
command after installing each library. For example::
|
||||
|
||||
$ sudo make install
|
||||
$ sudo ldconfig
|
||||
|
||||
.. note::
|
||||
|
||||
OS X users are required to install `Apple Developer Tools`_ in order
|
||||
to compile software from source. This is typically included on your
|
||||
OS X installation DVDs.
|
||||
|
||||
.. _Apple Developer Tools: https://developer.apple.com/technologies/tools/
|
||||
|
||||
.. _geosbuild:
|
||||
|
||||
GEOS
|
||||
----
|
||||
|
||||
GEOS is a C++ library for performing geometric operations, and is the default
|
||||
internal geometry representation used by GeoDjango (it's behind the "lazy"
|
||||
geometries). Specifically, the C API library is called (e.g., ``libgeos_c.so``)
|
||||
directly from Python using ctypes.
|
||||
|
||||
First, download GEOS 3.3.5 from the refractions Web site and untar the source
|
||||
archive::
|
||||
|
||||
$ wget http://download.osgeo.org/geos/geos-3.3.5.tar.bz2
|
||||
$ tar xjf geos-3.3.5.tar.bz2
|
||||
|
||||
Next, change into the directory where GEOS was unpacked, run the configure
|
||||
script, compile, and install::
|
||||
|
||||
$ cd geos-3.3.5
|
||||
$ ./configure
|
||||
$ make
|
||||
$ sudo make install
|
||||
$ cd ..
|
||||
|
||||
Troubleshooting
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
Can't find GEOS library
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When GeoDjango can't find GEOS, this error is raised:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
ImportError: Could not find the GEOS library (tried "geos_c"). Try setting GEOS_LIBRARY_PATH in your settings.
|
||||
|
||||
The most common solution is to properly configure your :ref:`libsettings` *or* set
|
||||
:ref:`geoslibrarypath` in your settings.
|
||||
|
||||
If using a binary package of GEOS (e.g., on Ubuntu), you may need to :ref:`binutils`.
|
||||
|
||||
.. _geoslibrarypath:
|
||||
|
||||
``GEOS_LIBRARY_PATH``
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If your GEOS library is in a non-standard location, or you don't want to
|
||||
modify the system's library path then the :setting:`GEOS_LIBRARY_PATH`
|
||||
setting may be added to your Django settings file with the full path to the
|
||||
GEOS C library. For example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
GEOS_LIBRARY_PATH = '/home/bob/local/lib/libgeos_c.so'
|
||||
|
||||
.. note::
|
||||
|
||||
The setting must be the *full* path to the **C** shared library; in
|
||||
other words you want to use ``libgeos_c.so``, not ``libgeos.so``.
|
||||
|
||||
See also :ref:`My logs are filled with GEOS-related errors <geos-exceptions-in-logfile>`.
|
||||
|
||||
.. _proj4:
|
||||
|
||||
PROJ.4
|
||||
------
|
||||
|
||||
`PROJ.4`_ is a library for converting geospatial data to different coordinate
|
||||
reference systems.
|
||||
|
||||
First, download the PROJ.4 source code and datum shifting files [#]_::
|
||||
|
||||
$ wget http://download.osgeo.org/proj/proj-4.8.0.tar.gz
|
||||
$ wget http://download.osgeo.org/proj/proj-datumgrid-1.5.tar.gz
|
||||
|
||||
Next, untar the source code archive, and extract the datum shifting files in the
|
||||
``nad`` subdirectory. This must be done *prior* to configuration::
|
||||
|
||||
$ tar xzf proj-4.8.0.tar.gz
|
||||
$ cd proj-4.8.0/nad
|
||||
$ tar xzf ../../proj-datumgrid-1.5.tar.gz
|
||||
$ cd ..
|
||||
|
||||
Finally, configure, make and install PROJ.4::
|
||||
|
||||
$ ./configure
|
||||
$ make
|
||||
$ sudo make install
|
||||
$ cd ..
|
||||
|
||||
.. _gdalbuild:
|
||||
|
||||
GDAL
|
||||
----
|
||||
|
||||
`GDAL`__ is an excellent open source geospatial library that has support for
|
||||
reading most vector and raster spatial data formats. Currently, GeoDjango only
|
||||
supports :ref:`GDAL's vector data <ref-gdal>` capabilities [#]_.
|
||||
:ref:`geosbuild` and :ref:`proj4` should be installed prior to building GDAL.
|
||||
|
||||
First download the latest GDAL release version and untar the archive::
|
||||
|
||||
$ wget http://download.osgeo.org/gdal/gdal-1.9.1.tar.gz
|
||||
$ tar xzf gdal-1.9.1.tar.gz
|
||||
$ cd gdal-1.9.1
|
||||
|
||||
Configure, make and install::
|
||||
|
||||
$ ./configure
|
||||
$ make # Go get some coffee, this takes a while.
|
||||
$ sudo make install
|
||||
$ cd ..
|
||||
|
||||
.. note::
|
||||
|
||||
Because GeoDjango has it's own Python interface, the preceding instructions
|
||||
do not build GDAL's own Python bindings. The bindings may be built by
|
||||
adding the ``--with-python`` flag when running ``configure``. See
|
||||
`GDAL/OGR In Python`__ for more information on GDAL's bindings.
|
||||
|
||||
If you have any problems, please see the troubleshooting section below for
|
||||
suggestions and solutions.
|
||||
|
||||
__ http://trac.osgeo.org/gdal/
|
||||
__ http://trac.osgeo.org/gdal/wiki/GdalOgrInPython
|
||||
|
||||
.. _gdaltrouble:
|
||||
|
||||
Troubleshooting
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
Can't find GDAL library
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When GeoDjango can't find the GDAL library, the ``HAS_GDAL`` flag
|
||||
will be false:
|
||||
|
||||
.. code-block:: pycon
|
||||
|
||||
>>> from django.contrib.gis import gdal
|
||||
>>> gdal.HAS_GDAL
|
||||
False
|
||||
|
||||
The solution is to properly configure your :ref:`libsettings` *or* set
|
||||
:ref:`gdallibrarypath` in your settings.
|
||||
|
||||
.. _gdallibrarypath:
|
||||
|
||||
``GDAL_LIBRARY_PATH``
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If your GDAL library is in a non-standard location, or you don't want to
|
||||
modify the system's library path then the :setting:`GDAL_LIBRARY_PATH`
|
||||
setting may be added to your Django settings file with the full path to
|
||||
the GDAL library. For example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
GDAL_LIBRARY_PATH = '/home/sue/local/lib/libgdal.so'
|
||||
|
||||
.. _gdaldata:
|
||||
|
||||
Can't find GDAL data files (``GDAL_DATA``)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When installed from source, GDAL versions 1.5.1 and below have an autoconf bug
|
||||
that places data in the wrong location. [#]_ This can lead to error messages
|
||||
like this:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
ERROR 4: Unable to open EPSG support file gcs.csv.
|
||||
...
|
||||
OGRException: OGR failure.
|
||||
|
||||
The solution is to set the ``GDAL_DATA`` environment variable to the location of the
|
||||
GDAL data files before invoking Python (typically ``/usr/local/share``; use
|
||||
``gdal-config --datadir`` to find out). For example::
|
||||
|
||||
$ export GDAL_DATA=`gdal-config --datadir`
|
||||
$ python manage.py shell
|
||||
|
||||
If using Apache, you may need to add this environment variable to your configuration
|
||||
file:
|
||||
|
||||
.. code-block:: apache
|
||||
|
||||
SetEnv GDAL_DATA /usr/local/share
|
||||
|
||||
.. rubric:: Footnotes
|
||||
.. [#] The datum shifting files are needed for converting data to and from
|
||||
certain projections.
|
||||
For example, the PROJ.4 string for the `Google projection (900913 or 3857)
|
||||
<http://spatialreference.org/ref/sr-org/6864/prj/>`_ requires the
|
||||
``null`` grid file only included in the extra datum shifting files.
|
||||
It is easier to install the shifting files now, then to have debug a
|
||||
problem caused by their absence later.
|
||||
.. [#] Specifically, GeoDjango provides support for the `OGR
|
||||
<http://gdal.org/ogr>`_ library, a component of GDAL.
|
||||
.. [#] See `GDAL ticket #2382 <http://trac.osgeo.org/gdal/ticket/2382>`_.
|
||||
|
||||
|
|
@ -0,0 +1,535 @@
|
|||
.. _ref-gis-install:
|
||||
|
||||
======================
|
||||
GeoDjango Installation
|
||||
======================
|
||||
|
||||
.. highlight:: console
|
||||
|
||||
Overview
|
||||
========
|
||||
In general, GeoDjango installation requires:
|
||||
|
||||
1. :ref:`Python and Django <django>`
|
||||
2. :ref:`spatial_database`
|
||||
3. :ref:`geospatial_libs`
|
||||
|
||||
Details for each of the requirements and installation instructions
|
||||
are provided in the sections below. In addition, platform-specific
|
||||
instructions are available for:
|
||||
|
||||
* :ref:`macosx`
|
||||
* :ref:`windows`
|
||||
|
||||
.. admonition:: Use the Source
|
||||
|
||||
Because GeoDjango takes advantage of the latest in the open source geospatial
|
||||
software technology, recent versions of the libraries are necessary.
|
||||
If binary packages aren't available for your platform, installation from
|
||||
source may be required. When compiling the libraries from source, please
|
||||
follow the directions closely, especially if you're a beginner.
|
||||
|
||||
Requirements
|
||||
============
|
||||
|
||||
.. _django:
|
||||
|
||||
Python and Django
|
||||
-----------------
|
||||
|
||||
Because GeoDjango is included with Django, please refer to Django's
|
||||
:ref:`installation instructions <installing-official-release>` for details on
|
||||
how to install.
|
||||
|
||||
|
||||
.. _spatial_database:
|
||||
|
||||
Spatial database
|
||||
----------------
|
||||
PostgreSQL (with PostGIS), MySQL, Oracle, and SQLite (with SpatiaLite) are
|
||||
the spatial databases currently supported.
|
||||
|
||||
.. note::
|
||||
|
||||
PostGIS is recommended, because it is the most mature and feature-rich
|
||||
open source spatial database.
|
||||
|
||||
The geospatial libraries required for a GeoDjango installation depends
|
||||
on the spatial database used. The following lists the library requirements,
|
||||
supported versions, and any notes for each of the supported database backends:
|
||||
|
||||
================== ============================== ================== =========================================
|
||||
Database Library Requirements Supported Versions Notes
|
||||
================== ============================== ================== =========================================
|
||||
PostgreSQL GEOS, PROJ.4, PostGIS 8.2+ Requires PostGIS.
|
||||
MySQL GEOS 5.x Not OGC-compliant; limited functionality.
|
||||
Oracle GEOS 10.2, 11 XE not supported; not tested with 9.
|
||||
SQLite GEOS, GDAL, PROJ.4, SpatiaLite 3.6.+ Requires SpatiaLite 2.3+, pysqlite2 2.5+
|
||||
================== ============================== ================== =========================================
|
||||
|
||||
See also `this comparison matrix`__ on the OSGeo Wiki for
|
||||
PostgreSQL/PostGIS/GEOS/GDAL possible combinations.
|
||||
|
||||
__ http://trac.osgeo.org/postgis/wiki/UsersWikiPostgreSQLPostGIS
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
Geospatial libraries
|
||||
--------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
geolibs
|
||||
|
||||
Database installation
|
||||
---------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
postgis
|
||||
spatialite
|
||||
|
||||
Add ``django.contrib.gis`` to :setting:`INSTALLED_APPS`
|
||||
-------------------------------------------------------
|
||||
|
||||
Like other Django contrib applications, you will *only* need to add
|
||||
:mod:`django.contrib.gis` to :setting:`INSTALLED_APPS` in your settings.
|
||||
This is the so that ``gis`` templates can be located -- if not done, then
|
||||
features such as the geographic admin or KML sitemaps will not function properly.
|
||||
|
||||
.. _addgoogleprojection:
|
||||
|
||||
Add Google projection to ``spatial_ref_sys`` table
|
||||
--------------------------------------------------
|
||||
|
||||
.. note::
|
||||
|
||||
If you're running PostGIS 1.4 or above, you can skip this step. The entry
|
||||
is already included in the default ``spatial_ref_sys`` table.
|
||||
|
||||
In order to conduct database transformations to the so-called "Google"
|
||||
projection (a spherical mercator projection used by Google Maps),
|
||||
an entry must be added to your spatial database's ``spatial_ref_sys`` table.
|
||||
Invoke the Django shell from your project and execute the
|
||||
``add_srs_entry`` function:
|
||||
|
||||
.. code-block:: pycon
|
||||
|
||||
$ python manage shell
|
||||
>>> from django.contrib.gis.utils import add_srs_entry
|
||||
>>> add_srs_entry(900913)
|
||||
|
||||
This adds an entry for the 900913 SRID to the ``spatial_ref_sys`` (or equivalent)
|
||||
table, making it possible for the spatial database to transform coordinates in
|
||||
this projection. You only need to execute this command *once* per spatial database.
|
||||
|
||||
Troubleshooting
|
||||
===============
|
||||
|
||||
If you can't find the solution to your problem here then participate in the
|
||||
community! You can:
|
||||
|
||||
* Join the ``#geodjango`` IRC channel on FreeNode. Please be patient and polite
|
||||
-- while you may not get an immediate response, someone will attempt to answer
|
||||
your question as soon as they see it.
|
||||
* Ask your question on the `GeoDjango`__ mailing list.
|
||||
* File a ticket on the `Django trac`__ if you think there's a bug. Make
|
||||
sure to provide a complete description of the problem, versions used,
|
||||
and specify the component as "GIS".
|
||||
|
||||
__ http://groups.google.com/group/geodjango
|
||||
__ https://code.djangoproject.com/newticket
|
||||
|
||||
.. _libsettings:
|
||||
|
||||
Library environment settings
|
||||
----------------------------
|
||||
|
||||
By far, the most common problem when installing GeoDjango is that the
|
||||
external shared libraries (e.g., for GEOS and GDAL) cannot be located. [#]_
|
||||
Typically, the cause of this problem is that the operating system isn't aware
|
||||
of the directory where the libraries built from source were installed.
|
||||
|
||||
In general, the library path may be set on a per-user basis by setting
|
||||
an environment variable, or by configuring the library path for the entire
|
||||
system.
|
||||
|
||||
``LD_LIBRARY_PATH`` environment variable
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
A user may set this environment variable to customize the library paths
|
||||
they want to use. The typical library directory for software
|
||||
built from source is ``/usr/local/lib``. Thus, ``/usr/local/lib`` needs
|
||||
to be included in the ``LD_LIBRARY_PATH`` variable. For example, the user
|
||||
could place the following in their bash profile::
|
||||
|
||||
export LD_LIBRARY_PATH=/usr/local/lib
|
||||
|
||||
Setting system library path
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
On GNU/Linux systems, there is typically a file in ``/etc/ld.so.conf``, which may include
|
||||
additional paths from files in another directory, such as ``/etc/ld.so.conf.d``.
|
||||
As the root user, add the custom library path (like ``/usr/local/lib``) on a
|
||||
new line in ``ld.so.conf``. This is *one* example of how to do so::
|
||||
|
||||
$ sudo echo /usr/local/lib >> /etc/ld.so.conf
|
||||
$ sudo ldconfig
|
||||
|
||||
For OpenSolaris users, the system library path may be modified using the
|
||||
``crle`` utility. Run ``crle`` with no options to see the current configuration
|
||||
and use ``crle -l`` to set with the new library path. Be *very* careful when
|
||||
modifying the system library path::
|
||||
|
||||
# crle -l $OLD_PATH:/usr/local/lib
|
||||
|
||||
.. _binutils:
|
||||
|
||||
Install ``binutils``
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
GeoDjango uses the ``find_library`` function (from the ``ctypes.util`` Python
|
||||
module) to discover libraries. The ``find_library`` routine uses a program
|
||||
called ``objdump`` (part of the ``binutils`` package) to verify a shared
|
||||
library on GNU/Linux systems. Thus, if ``binutils`` is not installed on your
|
||||
Linux system then Python's ctypes may not be able to find your library even if
|
||||
your library path is set correctly and geospatial libraries were built perfectly.
|
||||
|
||||
The ``binutils`` package may be installed on Debian and Ubuntu systems using the
|
||||
following command::
|
||||
|
||||
$ sudo apt-get install binutils
|
||||
|
||||
Similarly, on Red Hat and CentOS systems::
|
||||
|
||||
$ sudo yum install binutils
|
||||
|
||||
Platform-specific instructions
|
||||
==============================
|
||||
|
||||
.. _macosx:
|
||||
|
||||
Mac OS X
|
||||
--------
|
||||
|
||||
Because of the variety of packaging systems available for OS X, users have
|
||||
several different options for installing GeoDjango. These options are:
|
||||
|
||||
* :ref:`homebrew`
|
||||
* :ref:`kyngchaos`
|
||||
* :ref:`fink`
|
||||
* :ref:`macports`
|
||||
* :ref:`build_from_source`
|
||||
|
||||
.. note::
|
||||
|
||||
Currently, the easiest and recommended approach for installing GeoDjango
|
||||
on OS X is to use the KyngChaos packages.
|
||||
|
||||
This section also includes instructions for installing an upgraded version
|
||||
of :ref:`macosx_python` from packages provided by the Python Software
|
||||
Foundation, however, this is not required.
|
||||
|
||||
.. _macosx_python:
|
||||
|
||||
Python
|
||||
^^^^^^
|
||||
|
||||
Although OS X comes with Python installed, users can use framework
|
||||
installers (`2.6`__ and `2.7`__ are available) provided by
|
||||
the Python Software Foundation. An advantage to using the installer is
|
||||
that OS X's Python will remain "pristine" for internal operating system
|
||||
use.
|
||||
|
||||
__ http://python.org/ftp/python/2.6.6/python-2.6.6-macosx10.3.dmg
|
||||
__ http://python.org/ftp/python/2.7.3/
|
||||
|
||||
.. note::
|
||||
|
||||
You will need to modify the ``PATH`` environment variable in your
|
||||
``.profile`` file so that the new version of Python is used when
|
||||
``python`` is entered at the command-line::
|
||||
|
||||
export PATH=/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH
|
||||
|
||||
.. _homebrew:
|
||||
|
||||
Homebrew
|
||||
^^^^^^^^
|
||||
|
||||
`Homebrew`__ provides "recipes" for building binaries and packages from source.
|
||||
It provides recipes for the GeoDjango prerequisites on Macintosh computers
|
||||
running OS X. Because Homebrew still builds the software from source, the
|
||||
`Apple Developer Tools`_ are required.
|
||||
|
||||
Summary::
|
||||
|
||||
$ brew install postgresql
|
||||
$ brew install postgis
|
||||
$ brew install gdal
|
||||
$ brew install libgeoip
|
||||
|
||||
__ http://mxcl.github.com/homebrew/
|
||||
.. _Apple Developer Tools: https://developer.apple.com/technologies/tools/
|
||||
|
||||
.. _kyngchaos:
|
||||
|
||||
KyngChaos packages
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
William Kyngesburye provides a number of `geospatial library binary packages`__
|
||||
that make it simple to get GeoDjango installed on OS X without compiling
|
||||
them from source. However, the `Apple Developer Tools`_ are still necessary
|
||||
for compiling the Python database adapters :ref:`psycopg2_kyngchaos` (for PostGIS)
|
||||
and :ref:`pysqlite2` (for SpatiaLite).
|
||||
|
||||
.. note::
|
||||
|
||||
SpatiaLite users should consult the :ref:`spatialite_macosx` section
|
||||
after installing the packages for additional instructions.
|
||||
|
||||
Download the framework packages for:
|
||||
|
||||
* UnixImageIO
|
||||
* PROJ
|
||||
* GEOS
|
||||
* SQLite3 (includes the SpatiaLite library)
|
||||
* GDAL
|
||||
|
||||
Install the packages in the order they are listed above, as the GDAL and SQLite
|
||||
packages require the packages listed before them.
|
||||
|
||||
Afterwards, you can also install the KyngChaos binary packages for `PostgreSQL
|
||||
and PostGIS`__.
|
||||
|
||||
After installing the binary packages, you'll want to add the following to
|
||||
your ``.profile`` to be able to run the package programs from the command-line::
|
||||
|
||||
export PATH=/Library/Frameworks/UnixImageIO.framework/Programs:$PATH
|
||||
export PATH=/Library/Frameworks/PROJ.framework/Programs:$PATH
|
||||
export PATH=/Library/Frameworks/GEOS.framework/Programs:$PATH
|
||||
export PATH=/Library/Frameworks/SQLite3.framework/Programs:$PATH
|
||||
export PATH=/Library/Frameworks/GDAL.framework/Programs:$PATH
|
||||
export PATH=/usr/local/pgsql/bin:$PATH
|
||||
|
||||
__ http://www.kyngchaos.com/software/frameworks
|
||||
__ http://www.kyngchaos.com/software/postgres
|
||||
|
||||
.. _psycopg2_kyngchaos:
|
||||
|
||||
psycopg2
|
||||
~~~~~~~~
|
||||
|
||||
After you've installed the KyngChaos binaries and modified your ``PATH``, as
|
||||
described above, ``psycopg2`` may be installed using the following command::
|
||||
|
||||
$ sudo pip install psycopg2
|
||||
|
||||
.. note::
|
||||
|
||||
If you don't have ``pip``, follow the the :ref:`installation instructions
|
||||
<installing-official-release>` to install it.
|
||||
|
||||
.. _fink:
|
||||
|
||||
Fink
|
||||
^^^^
|
||||
|
||||
`Kurt Schwehr`__ has been gracious enough to create GeoDjango packages for users
|
||||
of the `Fink`__ package system. The following packages are available, depending
|
||||
on which version of Python you want to use:
|
||||
|
||||
* ``django-gis-py26``
|
||||
* ``django-gis-py25``
|
||||
* ``django-gis-py24``
|
||||
|
||||
__ http://schwehr.org/blog/
|
||||
__ http://www.finkproject.org/
|
||||
|
||||
.. _macports:
|
||||
|
||||
MacPorts
|
||||
^^^^^^^^
|
||||
|
||||
`MacPorts`__ may be used to install GeoDjango prerequisites on Macintosh
|
||||
computers running OS X. Because MacPorts still builds the software from source,
|
||||
the `Apple Developer Tools`_ are required.
|
||||
|
||||
Summary::
|
||||
|
||||
$ sudo port install postgresql83-server
|
||||
$ sudo port install geos
|
||||
$ sudo port install proj
|
||||
$ sudo port install postgis
|
||||
$ sudo port install gdal +geos
|
||||
$ sudo port install libgeoip
|
||||
|
||||
.. note::
|
||||
|
||||
You will also have to modify the ``PATH`` in your ``.profile`` so
|
||||
that the MacPorts programs are accessible from the command-line::
|
||||
|
||||
export PATH=/opt/local/bin:/opt/local/lib/postgresql83/bin
|
||||
|
||||
In addition, add the ``DYLD_FALLBACK_LIBRARY_PATH`` setting so that
|
||||
the libraries can be found by Python::
|
||||
|
||||
export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:/opt/local/lib/postgresql83
|
||||
|
||||
__ http://www.macports.org/
|
||||
|
||||
.. _windows:
|
||||
|
||||
Windows
|
||||
-------
|
||||
|
||||
Proceed through the following sections sequentially in order to install
|
||||
GeoDjango on Windows.
|
||||
|
||||
.. note::
|
||||
|
||||
These instructions assume that you are using 32-bit versions of
|
||||
all programs. While 64-bit versions of Python and PostgreSQL 9.0
|
||||
are available, 64-bit versions of spatial libraries, like
|
||||
GEOS and GDAL, are not yet provided by the :ref:`OSGeo4W` installer.
|
||||
|
||||
Python
|
||||
^^^^^^
|
||||
|
||||
First, download the latest `Python 2.7 installer`__ from the Python Web site.
|
||||
Next, run the installer and keep the defaults -- for example, keep
|
||||
'Install for all users' checked and the installation path set as
|
||||
``C:\Python27``.
|
||||
|
||||
.. note::
|
||||
|
||||
You may already have a version of Python installed in ``C:\python`` as ESRI
|
||||
products sometimes install a copy there. *You should still install a
|
||||
fresh version of Python 2.7.*
|
||||
|
||||
__ http://python.org/download/
|
||||
|
||||
PostgreSQL
|
||||
^^^^^^^^^^
|
||||
|
||||
First, download the latest `PostgreSQL 9.0 installer`__ from the
|
||||
`EnterpriseDB`__ Web site. After downloading, simply run the installer,
|
||||
follow the on-screen directions, and keep the default options unless
|
||||
you know the consequences of changing them.
|
||||
|
||||
.. note::
|
||||
|
||||
The PostgreSQL installer creates both a new Windows user to be the
|
||||
'postgres service account' and a ``postgres`` database superuser
|
||||
You will be prompted once to set the password for both accounts --
|
||||
make sure to remember it!
|
||||
|
||||
When the installer completes, it will ask to launch the Application Stack
|
||||
Builder (ASB) on exit -- keep this checked, as it is necessary to
|
||||
install :ref:`postgisasb`.
|
||||
|
||||
.. note::
|
||||
|
||||
If installed successfully, the PostgreSQL server will run in the
|
||||
background each time the system as started as a Windows service.
|
||||
A :menuselection:`PostgreSQL 9.0` start menu group will created
|
||||
and contains shortcuts for the ASB as well as the 'SQL Shell',
|
||||
which will launch a ``psql`` command window.
|
||||
|
||||
__ http://www.enterprisedb.com/products-services-training/pgdownload
|
||||
__ http://www.enterprisedb.com
|
||||
|
||||
.. _postgisasb:
|
||||
|
||||
PostGIS
|
||||
^^^^^^^
|
||||
|
||||
From within the Application Stack Builder (to run outside of the installer,
|
||||
:menuselection:`Start --> Programs --> PostgreSQL 9.0`), select
|
||||
:menuselection:`PostgreSQL Database Server 9.0 on port 5432` from the drop down
|
||||
menu. Next, expand the :menuselection:`Categories --> Spatial Extensions` menu
|
||||
tree and select :menuselection:`PostGIS 1.5 for PostgreSQL 9.0`.
|
||||
|
||||
After clicking next, you will be prompted to select your mirror, PostGIS
|
||||
will be downloaded, and the PostGIS installer will begin. Select only the
|
||||
default options during install (e.g., do not uncheck the option to create a
|
||||
default PostGIS database).
|
||||
|
||||
.. note::
|
||||
|
||||
You will be prompted to enter your ``postgres`` database superuser
|
||||
password in the 'Database Connection Information' dialog.
|
||||
|
||||
psycopg2
|
||||
^^^^^^^^
|
||||
|
||||
The ``psycopg2`` Python module provides the interface between Python and the
|
||||
PostgreSQL database. Download the latest `Windows installer`__ for your version
|
||||
of Python and PostgreSQL and run using the default settings. [#]_
|
||||
|
||||
__ http://www.stickpeople.com/projects/python/win-psycopg/
|
||||
|
||||
.. _osgeo4w:
|
||||
|
||||
OSGeo4W
|
||||
^^^^^^^
|
||||
|
||||
The `OSGeo4W installer`_ makes it simple to install the PROJ.4, GDAL, and GEOS
|
||||
libraries required by GeoDjango. First, download the `OSGeo4W installer`_,
|
||||
and run it. Select :menuselection:`Express Web-GIS Install` and click next.
|
||||
In the 'Select Packages' list, ensure that GDAL is selected; MapServer and
|
||||
Apache are also enabled by default, but are not required by GeoDjango and
|
||||
may be unchecked safely. After clicking next, the packages will be
|
||||
automatically downloaded and installed, after which you may exit the
|
||||
installer.
|
||||
|
||||
.. _OSGeo4W installer: http://trac.osgeo.org/osgeo4w/
|
||||
|
||||
Modify Windows environment
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In order to use GeoDjango, you will need to add your Python and OSGeo4W
|
||||
directories to your Windows system ``Path``, as well as create ``GDAL_DATA``
|
||||
and ``PROJ_LIB`` environment variables. The following set of commands,
|
||||
executable with ``cmd.exe``, will set this up:
|
||||
|
||||
.. code-block:: bat
|
||||
|
||||
set OSGEO4W_ROOT=C:\OSGeo4W
|
||||
set PYTHON_ROOT=C:\Python27
|
||||
set GDAL_DATA=%OSGEO4W_ROOT%\share\gdal
|
||||
set PROJ_LIB=%OSGEO4W_ROOT%\share\proj
|
||||
set PATH=%PATH%;%PYTHON_ROOT%;%OSGEO4W_ROOT%\bin
|
||||
reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v Path /t REG_EXPAND_SZ /f /d "%PATH%"
|
||||
reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v GDAL_DATA /t REG_EXPAND_SZ /f /d "%GDAL_DATA%"
|
||||
reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v PROJ_LIB /t REG_EXPAND_SZ /f /d "%PROJ_LIB%"
|
||||
|
||||
For your convenience, these commands are available in the executable batch
|
||||
script, :download:`geodjango_setup.bat`.
|
||||
|
||||
.. note::
|
||||
|
||||
Administrator privileges are required to execute these commands.
|
||||
To do this, right-click on :download:`geodjango_setup.bat` and select
|
||||
:menuselection:`Run as administrator`. You need to log out and log back in again
|
||||
for the settings to take effect.
|
||||
|
||||
.. note::
|
||||
|
||||
If you customized the Python or OSGeo4W installation directories,
|
||||
then you will need to modify the ``OSGEO4W_ROOT`` and/or ``PYTHON_ROOT``
|
||||
variables accordingly.
|
||||
|
||||
Install Django and set up database
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Finally, :ref:`install Django <installing-official-release>` on your system.
|
||||
|
||||
.. rubric:: Footnotes
|
||||
.. [#] GeoDjango uses the :func:`~ctypes.util.find_library` routine from
|
||||
:mod:`ctypes.util` to locate shared libraries.
|
||||
.. [#] The ``psycopg2`` Windows installers are packaged and maintained by
|
||||
`Jason Erickson <http://www.stickpeople.com/projects/python/win-psycopg/>`_.
|
||||
|
|
@ -0,0 +1,175 @@
|
|||
.. _postgis:
|
||||
|
||||
==================
|
||||
Installing PostGIS
|
||||
==================
|
||||
|
||||
`PostGIS`__ adds geographic object support to PostgreSQL, turning it
|
||||
into a spatial database. :ref:`geosbuild`, :ref:`proj4` and
|
||||
:ref:`gdalbuild` should be installed prior to building PostGIS. You
|
||||
might also need additional libraries, see `PostGIS requirements`_.
|
||||
|
||||
.. note::
|
||||
|
||||
The `psycopg2`_ module is required for use as the database adaptor
|
||||
when using GeoDjango with PostGIS.
|
||||
|
||||
.. _psycopg2: http://initd.org/psycopg/
|
||||
.. _PostGIS requirements: http://www.postgis.org/documentation/manual-2.0/postgis_installation.html#id2711662
|
||||
|
||||
On Debian/Ubuntu, you are advised to install the following packages:
|
||||
postgresql-x.x, postgresql-x.x-postgis, postgresql-server-dev-x.x,
|
||||
python-psycopg2 (x.x matching the PostgreSQL version you want to install).
|
||||
Please also consult platform-specific instructions if you are on :ref:`macosx`
|
||||
or :ref:`windows`.
|
||||
|
||||
Building from source
|
||||
====================
|
||||
|
||||
First download the source archive, and extract::
|
||||
|
||||
$ wget http://postgis.refractions.net/download/postgis-2.0.1.tar.gz
|
||||
$ tar xzf postgis-2.0.1.tar.gz
|
||||
$ cd postgis-2.0.1
|
||||
|
||||
Next, configure, make and install PostGIS::
|
||||
|
||||
$ ./configure
|
||||
|
||||
Finally, make and install::
|
||||
|
||||
$ make
|
||||
$ sudo make install
|
||||
$ cd ..
|
||||
|
||||
.. note::
|
||||
|
||||
GeoDjango does not automatically create a spatial database. Please consult
|
||||
the section on :ref:`spatialdb_template91` or
|
||||
:ref:`spatialdb_template_earlier` for more information.
|
||||
|
||||
__ http://postgis.refractions.net/
|
||||
|
||||
Post-installation
|
||||
=================
|
||||
|
||||
.. _spatialdb_template:
|
||||
.. _spatialdb_template91:
|
||||
|
||||
Creating a spatial database with PostGIS 2.0 and PostgreSQL 9.1
|
||||
---------------------------------------------------------------
|
||||
|
||||
PostGIS 2 includes an extension for Postgres 9.1 that can be used to enable
|
||||
spatial functionality::
|
||||
|
||||
$ createdb <db name>
|
||||
$ psql <db name>
|
||||
> CREATE EXTENSION postgis;
|
||||
> CREATE EXTENSION postgis_topology;
|
||||
|
||||
No PostGIS topology functionalities are yet available from GeoDjango, so the
|
||||
creation of the ``postgis_topology`` extension is entirely optional.
|
||||
|
||||
.. _spatialdb_template_earlier:
|
||||
|
||||
Creating a spatial database template for earlier versions
|
||||
---------------------------------------------------------
|
||||
|
||||
If you have an earlier version of PostGIS or PostgreSQL, the CREATE
|
||||
EXTENSION isn't available and you need to create the spatial database
|
||||
using the following instructions.
|
||||
|
||||
Creating a spatial database with PostGIS is different than normal because
|
||||
additional SQL must be loaded to enable spatial functionality. Because of
|
||||
the steps in this process, it's better to create a database template that
|
||||
can be reused later.
|
||||
|
||||
First, you need to be able to execute the commands as a privileged database
|
||||
user. For example, you can use the following to become the ``postgres`` user::
|
||||
|
||||
$ sudo su - postgres
|
||||
|
||||
.. note::
|
||||
|
||||
The location *and* name of the PostGIS SQL files (e.g., from
|
||||
``POSTGIS_SQL_PATH`` below) depends on the version of PostGIS.
|
||||
PostGIS versions 1.3 and below use ``<pg_sharedir>/contrib/lwpostgis.sql``;
|
||||
whereas version 1.4 uses ``<sharedir>/contrib/postgis.sql`` and
|
||||
version 1.5 uses ``<sharedir>/contrib/postgis-1.5/postgis.sql``.
|
||||
|
||||
To complicate matters, Debian/Ubuntu distributions have their own separate
|
||||
directory naming system that might change with time. In this case, use the
|
||||
:download:`create_template_postgis-debian.sh` script.
|
||||
|
||||
The example below assumes PostGIS 1.5, thus you may need to modify
|
||||
``POSTGIS_SQL_PATH`` and the name of the SQL file for the specific
|
||||
version of PostGIS you are using.
|
||||
|
||||
Once you're a database super user, then you may execute the following commands
|
||||
to create a PostGIS spatial database template::
|
||||
|
||||
$ POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-2.0
|
||||
# Creating the template spatial database.
|
||||
$ createdb -E UTF8 template_postgis
|
||||
$ createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
|
||||
# Allows non-superusers the ability to create from this template
|
||||
$ psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
|
||||
# Loading the PostGIS SQL routines
|
||||
$ psql -d template_postgis -f $POSTGIS_SQL_PATH/postgis.sql
|
||||
$ psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
|
||||
# Enabling users to alter spatial tables.
|
||||
$ psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;"
|
||||
$ psql -d template_postgis -c "GRANT ALL ON geography_columns TO PUBLIC;"
|
||||
$ psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
|
||||
|
||||
These commands may be placed in a shell script for later use; for convenience
|
||||
the following scripts are available:
|
||||
|
||||
=============== =============================================
|
||||
PostGIS version Bash shell script
|
||||
=============== =============================================
|
||||
1.3 :download:`create_template_postgis-1.3.sh`
|
||||
1.4 :download:`create_template_postgis-1.4.sh`
|
||||
1.5 :download:`create_template_postgis-1.5.sh`
|
||||
Debian/Ubuntu :download:`create_template_postgis-debian.sh`
|
||||
=============== =============================================
|
||||
|
||||
Afterwards, you may create a spatial database by simply specifying
|
||||
``template_postgis`` as the template to use (via the ``-T`` option)::
|
||||
|
||||
$ createdb -T template_postgis <db name>
|
||||
|
||||
.. note::
|
||||
|
||||
While the ``createdb`` command does not require database super-user privileges,
|
||||
it must be executed by a database user that has permissions to create databases.
|
||||
You can create such a user with the following command::
|
||||
|
||||
$ createuser --createdb <user>
|
||||
|
||||
PostgreSQL's createdb fails
|
||||
---------------------------
|
||||
|
||||
When the PostgreSQL cluster uses a non-UTF8 encoding, the
|
||||
:file:`create_template_postgis-*.sh` script will fail when executing
|
||||
``createdb``::
|
||||
|
||||
createdb: database creation failed: ERROR: new encoding (UTF8) is incompatible
|
||||
with the encoding of the template database (SQL_ASCII)
|
||||
|
||||
The `current workaround`__ is to re-create the cluster using UTF8 (back up any
|
||||
databases before dropping the cluster).
|
||||
|
||||
__ http://jacobian.org/writing/pg-encoding-ubuntu/
|
||||
|
||||
Managing the database
|
||||
---------------------
|
||||
|
||||
To administer the database, you can either use the pgAdmin III program
|
||||
(:menuselection:`Start --> PostgreSQL 9.0 --> pgAdmin III`) or the
|
||||
SQL Shell (:menuselection:`Start --> PostgreSQL 9.0 --> SQL Shell`).
|
||||
For example, to create a ``geodjango`` spatial database and user, the following
|
||||
may be executed from the SQL Shell as the ``postgres`` user::
|
||||
|
||||
postgres# CREATE USER geodjango PASSWORD 'my_passwd';
|
||||
postgres# CREATE DATABASE geodjango OWNER geodjango TEMPLATE template_postgis ENCODING 'utf8';
|
||||
|
|
@ -0,0 +1,222 @@
|
|||
.. _spatialite:
|
||||
|
||||
=====================
|
||||
Installing Spatialite
|
||||
=====================
|
||||
|
||||
`SpatiaLite`__ adds spatial support to SQLite, turning it into a full-featured
|
||||
spatial database.
|
||||
|
||||
Check first if you can install Spatialite from system packages or binaries. For
|
||||
example, on Debian-based distributions, try to install the ``spatialite-bin``
|
||||
package. For Mac OS X, follow the
|
||||
:ref:`specific instructions below<spatialite_macosx>`. For Windows, you may
|
||||
find binaries on `Gaia-SINS`__ home page. In any case, you should always
|
||||
be able to :ref:`install from source<spatialite_source>`.
|
||||
|
||||
When you are done with the installation process, skip to :ref:`create_spatialite_db`.
|
||||
|
||||
__ https://www.gaia-gis.it/fossil/libspatialite
|
||||
__ http://www.gaia-gis.it/gaia-sins/
|
||||
|
||||
.. _spatialite_source:
|
||||
|
||||
Installing from source
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
:ref:`GEOS and PROJ.4<geospatial_libs>` should be installed prior to building
|
||||
SpatiaLite.
|
||||
|
||||
SQLite
|
||||
^^^^^^
|
||||
|
||||
Check first if SQLite is compiled with the `R*Tree module`__. Run the sqlite3
|
||||
command line interface and enter the following query::
|
||||
|
||||
sqlite> CREATE VIRTUAL TABLE testrtree USING rtree(id,minX,maxX,minY,maxY);
|
||||
|
||||
If you obtain an error, you will have to recompile SQLite from source. Otherwise,
|
||||
just skip this section.
|
||||
|
||||
To install from sources, download the latest amalgamation source archive from
|
||||
the `SQLite download page`__, and extract::
|
||||
|
||||
$ wget http://sqlite.org/sqlite-amalgamation-3.6.23.1.tar.gz
|
||||
$ tar xzf sqlite-amalgamation-3.6.23.1.tar.gz
|
||||
$ cd sqlite-3.6.23.1
|
||||
|
||||
Next, run the ``configure`` script -- however the ``CFLAGS`` environment variable
|
||||
needs to be customized so that SQLite knows to build the R*Tree module::
|
||||
|
||||
$ CFLAGS="-DSQLITE_ENABLE_RTREE=1" ./configure
|
||||
$ make
|
||||
$ sudo make install
|
||||
$ cd ..
|
||||
|
||||
__ http://www.sqlite.org/rtree.html
|
||||
__ http://www.sqlite.org/download.html
|
||||
|
||||
.. _spatialitebuild :
|
||||
|
||||
SpatiaLite library (``libspatialite``) and tools (``spatialite``)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Get the latest SpatiaLite library source and tools bundle from the
|
||||
`download page`__::
|
||||
|
||||
$ wget http://www.gaia-gis.it/gaia-sins/libspatialite-sources/libspatialite-amalgamation-2.4.0-5.tar.gz
|
||||
$ wget http://www.gaia-gis.it/gaia-sins/spatialite-tools-sources/spatialite-tools-2.4.0-5.tar.gz
|
||||
$ tar xzf libspatialite-amalgamation-2.4.0-5.tar.gz
|
||||
$ tar xzf spatialite-tools-2.4.0-5.tar.gz
|
||||
|
||||
Prior to attempting to build, please read the important notes below to see if
|
||||
customization of the ``configure`` command is necessary. If not, then run the
|
||||
``configure`` script, make, and install for the SpatiaLite library::
|
||||
|
||||
$ cd libspatialite-amalgamation-2.3.1
|
||||
$ ./configure # May need to modified, see notes below.
|
||||
$ make
|
||||
$ sudo make install
|
||||
$ cd .... _spatialite
|
||||
|
||||
Finally, do the same for the SpatiaLite tools::
|
||||
|
||||
$ cd spatialite-tools-2.3.1
|
||||
$ ./configure # May need to modified, see notes below.
|
||||
$ make
|
||||
$ sudo make install
|
||||
$ cd ..
|
||||
|
||||
.. note::
|
||||
|
||||
If you've installed GEOS and PROJ.4 from binary packages, you will have to specify
|
||||
their paths when running the ``configure`` scripts for *both* the library and the
|
||||
tools (the configure scripts look, by default, in ``/usr/local``). For example,
|
||||
on Debian/Ubuntu distributions that have GEOS and PROJ.4 packages, the command would be::
|
||||
|
||||
$ ./configure --with-proj-include=/usr/include --with-proj-lib=/usr/lib --with-geos-include=/usr/include --with-geos-lib=/usr/lib
|
||||
|
||||
.. note::
|
||||
|
||||
For Mac OS X users building from source, the SpatiaLite library *and* tools
|
||||
need to have their ``target`` configured::
|
||||
|
||||
$ ./configure --target=macosx
|
||||
|
||||
__ http://www.gaia-gis.it/gaia-sins/libspatialite-sources/
|
||||
|
||||
.. _pysqlite2:
|
||||
|
||||
pysqlite2
|
||||
^^^^^^^^^
|
||||
|
||||
If you are on Python 2.6, you will also have to compile pysqlite2, because
|
||||
``SpatiaLite`` must be loaded as an external extension, and the required
|
||||
``enable_load_extension`` method is only available in versions 2.5+ of
|
||||
pysqlite2. Thus, download pysqlite2 2.6, and untar::
|
||||
|
||||
$ wget http://pysqlite.googlecode.com/files/pysqlite-2.6.3.tar.gz
|
||||
$ tar xzf pysqlite-2.6.3.tar.gz
|
||||
$ cd pysqlite-2.6.3
|
||||
|
||||
Next, use a text editor (e.g., ``emacs`` or ``vi``) to edit the ``setup.cfg`` file
|
||||
to look like the following:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[build_ext]
|
||||
#define=
|
||||
include_dirs=/usr/local/include
|
||||
library_dirs=/usr/local/lib
|
||||
libraries=sqlite3
|
||||
#define=SQLITE_OMIT_LOAD_EXTENSION
|
||||
|
||||
or if you are on Mac OS X:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[build_ext]
|
||||
#define=
|
||||
include_dirs=/Library/Frameworks/SQLite3.framework/unix/include
|
||||
library_dirs=/Library/Frameworks/SQLite3.framework/unix/lib
|
||||
libraries=sqlite3
|
||||
#define=SQLITE_OMIT_LOAD_EXTENSION
|
||||
|
||||
.. note::
|
||||
|
||||
The important thing here is to make sure you comment out the
|
||||
``define=SQLITE_OMIT_LOAD_EXTENSION`` flag and that the ``include_dirs``
|
||||
and ``library_dirs`` settings are uncommented and set to the appropriate
|
||||
path if the SQLite header files and libraries are not in ``/usr/include``
|
||||
and ``/usr/lib``, respectively.
|
||||
|
||||
After modifying ``setup.cfg`` appropriately, then run the ``setup.py`` script
|
||||
to build and install::
|
||||
|
||||
$ sudo python setup.py install
|
||||
|
||||
.. _spatialite_macosx:
|
||||
|
||||
Mac OS X-specific instructions
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Mac OS X users should follow the instructions in the :ref:`kyngchaos` section,
|
||||
as it is much easier than building from source.
|
||||
|
||||
When :ref:`create_spatialite_db`, the ``spatialite`` program is required.
|
||||
However, instead of attempting to compile the SpatiaLite tools from source,
|
||||
download the `SpatiaLite Binaries`__ for OS X, and install ``spatialite`` in a
|
||||
location available in your ``PATH``. For example::
|
||||
|
||||
$ curl -O http://www.gaia-gis.it/spatialite/spatialite-tools-osx-x86-2.3.1.tar.gz
|
||||
$ tar xzf spatialite-tools-osx-x86-2.3.1.tar.gz
|
||||
$ cd spatialite-tools-osx-x86-2.3.1/bin
|
||||
$ sudo cp spatialite /Library/Frameworks/SQLite3.framework/Programs
|
||||
|
||||
Finally, for GeoDjango to be able to find the KyngChaos SpatiaLite library,
|
||||
add the following to your ``settings.py``:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
SPATIALITE_LIBRARY_PATH='/Library/Frameworks/SQLite3.framework/SQLite3'
|
||||
|
||||
__ http://www.gaia-gis.it/spatialite-2.3.1/binaries.html
|
||||
|
||||
.. _create_spatialite_db:
|
||||
|
||||
Creating a spatial database for SpatiaLite
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
After you've installed SpatiaLite, you'll need to create a number of spatial
|
||||
metadata tables in your database in order to perform spatial queries.
|
||||
|
||||
If you're using SpatiaLite 2.4 or newer, use the ``spatialite`` utility to
|
||||
call the ``InitSpatialMetaData()`` function, like this::
|
||||
|
||||
$ spatialite geodjango.db "SELECT InitSpatialMetaData();"
|
||||
the SPATIAL_REF_SYS table already contains some row(s)
|
||||
InitSpatiaMetaData ()error:"table spatial_ref_sys already exists"
|
||||
0
|
||||
|
||||
You can safely ignore the error messages shown. When you've done this, you can
|
||||
skip the rest of this section.
|
||||
|
||||
If you're using SpatiaLite 2.3, you'll need to download a
|
||||
database-initialization file and execute its SQL queries in your database.
|
||||
|
||||
First, get it from the `SpatiaLite Resources`__ page::
|
||||
|
||||
$ wget http://www.gaia-gis.it/spatialite-2.3.1/init_spatialite-2.3.sql.gz
|
||||
$ gunzip init_spatialite-2.3.sql.gz
|
||||
|
||||
Then, use the ``spatialite`` command to initialize a spatial database::
|
||||
|
||||
$ spatialite geodjango.db < init_spatialite-2.3.sql
|
||||
|
||||
.. note::
|
||||
|
||||
The parameter ``geodjango.db`` is the *filename* of the SQLite database
|
||||
you want to use. Use the same in the :setting:`DATABASES` ``"name"`` key
|
||||
inside your ``settings.py``.
|
||||
|
||||
__ http://www.gaia-gis.it/spatialite-2.3.1/resources.html
|
||||
Loading…
Reference in New Issue