GeoDjango A：安装

源自：http://geodjango.org/docs/install.html

======================
GeoDjango Installation
======================

Overview
========
In general, GeoDjango installation requires:

1. :ref:`python24` and :ref:`django`/*安装python平台及django框架*/
2. :ref:`spatial_database`/*空间数据库，如PostgresSQL*/
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:`debian`
* :ref:`ubuntu`
* :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.  
  Unfortunately, binary packages are not available on many GNU/Linux systems
  (GEOS 3, in particular). Thus, `installation from source`_ may be required.
  When compiling the libraries from source, please follow the directions closely, 
  especially if you're a beginner. 

.. _installation from source: install.html#building-from-source

Requirements
============

.. _python24:

Python 2.4+
-----------
Because of heavy use of the decorator syntax, Python 2.4 is minimum
version supported by GeoDjango. Python 2.5+ is recommended because the 
`ctypes`__ module comes included; otherwise, 2.4 users will need to 
`download and install ctypes`__.
/*推荐2.5版本，否则需要安装ctypes类库*/
__ http://docs.python.org/lib/module-ctypes.html
__ http://sourceforge.net/project/showfiles.php?group_id=71702

.. _django:

Django
------

Because GeoDjango is included with Django, please refer to Django's
`installation instructions`__ for details on how to install.

__ http://docs.djangoproject.com/en/dev/intro/install/

.. _spatial_database:

Spatial Database
----------------
PostgreSQL (with PostGIS), MySQL, and Oracle are the spatial databases
currently supported.
/*支持PostgreSQL、MySQL、Oracle，但不支持SQLServer*/
.. note ::

  PostGIS is recommended, because it is the most mature and feature-rich 
  open source spatial database.
/*此处使用推荐的PostgreSQL*/
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 spatial
databases:

================== ==================== ================== ==========================================
Spatial Database Library Requirements Supported Versions Notes
================== ==================== ================== ==========================================
PostgreSQL GEOS, PROJ.4 8.x Requires PostGIS; not tested with 7.x.
MySQL GEOS 5.x Not OGC-compliant; limited functionality.
Oracle GEOS 10.2 XE not supported; not tested with 9 or 11.
================== ==================== ================== ==========================================

.. _geospatial_libs:

Geospatial Libraries
--------------------
GeoDjango uses and/or provides interfaces for the the following open source 
geospatial libraries:

=========== ==================================== ===================== ====================
Program Description Required Supported Versions
=========== ==================================== ===================== ====================
`GEOS`_ Geometry Engine Open Source Yes 3.0.x, 3.0.0RC4
`PROJ.4`__ Cartographic Projections library Yes (PostgreSQL only) 4.6.x, 4.5.x, 4.4.x
`PostGIS`__ Spatial extensions for PostgreSQL Yes (PostgreSQL only) 1.3.x, 1.2.1
`GDAL`_ Geospatial Data Abstraction Library No 1.5.x, 1.4.x
`GeoIP`_ IP-based geolocation library No 1.4.x
=========== ==================================== ===================== ====================

While GDAL is optional, it is recommended because some GeoDjango utilities and 
functionality depend on its installation.

.. 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 ``django.contrib.gis``.

.. _GEOS: geos.html
.. _GDAL: gdal.html
.. _GeoIP: geoip.html

__ http://trac.osgeo.org/proj/
__ http://postgis.refractions.net/

.. _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.

.. _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.0.2 from the refractions website and untar the source 
archive::

  $ wget http://download.osgeo.org/geos/geos-3.0.2.tar.bz2
  $ tar xjf geos-3.0.2.tar.bz2

Next, change into the directory where GEOS was unpacked, run the configure 
script, compile, and install::

  $ cd geos-3.0.2
  $ ./configure
  $ make
  $ sudo make install
  $ cd ..

Troubleshooting
^^^^^^^^^^^^^^^

Can't find GEOS Library
~~~~~~~~~~~~~~~~~~~~~~~

When GeoDjango can't find GEOS, this error is raised::

  ImportError: Could not find the GEOS library (tried "geos_c"). Try setting GEOS_LIBRARY_PATH in your settings.

The solution is to properly configure your :ref:`libsettings` *or* set 
:ref:`geoslibrarypath` in your settings.

.. _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 ``GEOS_LIBRARY_PATH`` setting
may be added to your Django settings file with the full path to the GEOS
C library. For example::

  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``.

.. _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.6.1.tar.gz
  $ wget http://download.osgeo.org/proj/proj-datumgrid-1.4.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.6.1.tar.gz
  $ cd proj-4.6.1/nad
  $ tar xzf http://www.cnblogs.com/proj-datumgrid-1.4.tar.gz
  $ cd ..

Finally, configure, make and install PROJ.4::

  $ ./configure
  $ make
  $ sudo make install
  $ cd ..

__ http://trac.osgeo.org/proj/

.. _postgis:

PostGIS
-------
`PostGIS`__ adds geographic object support to PostgreSQL, turning it
into a spatial database. :ref:`geosbuild` and :ref:`proj4` should be 
installed prior to building PostGIS.

.. note ::

  The `psycopg2`_ module is required for use as the database adaptor 
  when using GeoDjango with PostGIS. Thus, the ``DATABASE_ENGINE`` 
  Django setting needs to be ``postgresql_psycopg2``.

.. _psycopg2: http://initd.org/projects/psycopg2


First download the source archive, and extract::

  $ wget http://postgis.refractions.net/download/postgis-1.3.3.tar.gz
  $ tar xzf postgis-1.3.3.tar.gz
  $ cd postgis-1.3.3

Next, find out PostgreSQL's 'share' directory, and specify it as the data root
directory when configuring. This ensures that PostGIS places its files in
a location consistent with the PostgreSQL installation::

  $ ./configure --datadir=`pg_config --sharedir`

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_template` for more information.

__ http://postgis.refractions.net/

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 GDAL's vector data capabilities [#]_. :ref:`geosbuild` and :ref:`proj4` 
should be installed prior to building GDAL.

First download the latest GDAL version and untar the archive::

  $ wget http://download.osgeo.org/gdal/gdal-1.5.3.tar.gz
  $ tar xzf gdal-1.5.3.tar.gz
  $ cd gdal-1.5.3

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::

  >>> 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 ``GDAL_LIBRARY_PATH`` setting
may be added to your Django settings file with the full path to the GDAL
library. For example::

  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::

  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 infoking 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::

  SetEnv GDAL_DATA /usr/local/share

.. _post_install:

Post-Installation
=================

.. _spatialdb_template:

Creating a Spatial Database Template
------------------------------------

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

Once you're a database super user, then you may execute the following commands
to create a PostGIS spatial database template::

  $ createdb -E UTF8 template_postgis # Creating the template spatial database.
  $ createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
  $ psql -d template_postgis -f `pg_config --sharedir`/lwpostgis.sql # Loading the PostGIS SQL routines
  $ psql -d template_postgis -f `pg_config --sharedir`/spatial_ref_sys.sql
  $ psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" # Enabling users to alter spatial tables.
  $ 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 `create_template_postgis.sh`__ script is provided here.

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 -U postgres -O <db user> <db name>

.. note::

  The ``createdb`` command must still be executed with the permissions of a 
  database super user (hence the ``-U postgres`` option). The database owner
  (``-O`` option) is the database user that will own the new database; you may need
  to create with the ``createuser`` command if it does not exist.

__ http://geodjango.org/docs/create_template_postgis.sh

Add ``django.contrib.gis`` to ``INSTALLED_APPS``
------------------------------------------------

Like other Django contrib applications, you will *only* need to add 
``django.contrib.gis`` to ``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.

Add Google Projection to ``spatial_ref_sys`` table
--------------------------------------------------

In order to use the geographic admin with the OpenStreetMap base layer
(e.g., you want to use ``OSMGeoAdmin``), then the so-called "Google" projection 
must be added to your spatial database's ``spatial_ref_sys`` table. Invoke
the Django shell from your project and execute the following command::

  $ ./manage shell
  >>> from django.contrib.gis.utils import add_postgis_srs
  >>> add_postgis_srs(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 (may be accessed via 
  `Mibbit`__).
* Ask your question on the `Django users`__ mailing list (make sure to have
  "GeoDjango" in the text of your message).
* 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://www.mibbit.com/?server=irc.freenode.net&channel=%23geodjango
__ http://groups.google.com/group/django-users
__ http://code.djangoproject.com/simpleticket

.. _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 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

.. note:
   
  On Mac OSX modify the ``DYLD_LIBRARY_PATH`` variable instead.

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

Platform Specific Instructions
==============================

.. _macosx:

Mac OSX
-------

Although OSX comes with Python installed, it is recommended that users
utilize the installers (`2.5`__ and `2.6`__ are available) provided by 
the Python Software Foundation. This is recommended because:

#. OSX's Python will remain "pristine" for internal operating system use.
#. OSX's Python is not linked to GNU Readline library (meaning no colors in IPython).

__ http://python.org/ftp/python/2.5.2/python-2.5.2-macosx.dmg
__ http://python.org/ftp/python/2.6/python-2.6-macosx2008-10-01.dmg

.. note::
  
  You will need to modify your ``PATH`` so that the new version is invoked
  from the shell when you invoke the ``python`` command. Please see the
  :ref:`macenv` section for more details.

MacPorts
^^^^^^^^

.. warning::

  This method is no longer the recommended method to install GeoDjango on
  Mac OSX. Specifically, MacPorts requires modification of the 
  ``DYLD_LIBRARY_PATH`` enviornment variable, which may cause conflicts 
  for binaries linked to libraries native to the OS (for example libxml2,
  or iconv). That said, this may simplify the install process for more
  advanced users.
   
`MacPorts`__ may be used to install GeoDjango prerequisites on Macintosh 
computers running OSX. Because MacPorts still builds the software from source, Apple's
Xcode 3.0 Developer Tools for the Leopard or 2.4.1 for Tiger are required. [#]_

Summary::

  $ sudo port install postgresql83-server
  $ sudo port install geos
  $ sudo port install proj
  $ sudo port install postgis
  $ sudo port install gdal
  $ sudo port install libgeoip  


__ http://www.macports.org/

.. _macenv:

Enviornment Settings
^^^^^^^^^^^^^^^^^^^^

Shell enviornment settings need to be set so that the proper Python installation is
used and so that GeoDjango may find the geospatial libraries. In order for these
settings to persist, they should be placed in your user's bash profile
(``.profile`` in your home directory).

``PATH``
~~~~~~~~
The path needs to include the location of the Python installation and binary paths
used by MacPorts. The following should be okay (assuming the rest of the path
is provided in place of the ellipsis)::

  export PATH=/Library/Frameworks/Python.framework/Versions/Current/bin:/opt/local/bin:/opt/local/lib/postgresql83/bin:...
   

``DYLD_LIBRARY_PATH``
~~~~~~~~~~~~~~~~~~~~~
This needs to include the default library and database library locations used 
by MacPorts. The following should suffice::

  export DYLD_LIBRARY_PATH=/opt/local/lib:/opt/local/lib/postgresql83


``GDAL_DATA``
^^^^^^^^^^^^^
GDAL versions 1.5.1 (used by MacPorts) and below have an autoconf bug that places 
GDAL's data files in the wrong location. This environment variable should be set
so that GDAL may find its data::

  export GDAL_DATA=/opt/local/share

.. _debian:

Debian GNU/Linux
----------------


.. _ubuntu:

Ubuntu GNU/Linux
----------------


.. _windows:

Windows XP
----------

Python
^^^^^^

First, download the `Python 2.5 installer`__ from the Python website. Next,
execute the installer and use defaults, i.e., keep 'Install for all users' 
checked and the installation path set as ``C:\Python25``.

.. 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.5.*

__ http://python.org/ftp/python/2.5.2/python-2.5.2.msi

PostgreSQL
^^^^^^^^^^

First, select a mirror and download the `PostgreSQL 8.3.3 installer`__ from the 
PostgreSQL website.

Once downloaded, extract all files from the zipped folder and double-click on the 
'postgresql-8.3' installer. During the PostgreSQL installation use only the default
options (i.e., keep the installation path as ``C:\Program Files\PostgreSQL\8.3``).

.. note::

  This PostgreSQL installation process will create both a new windows user to be the 
  'postgres service account' and a special 'postgres superuser' to own the database 
  cluster. You will be prompted to set a password for both users (make sure to write 
  them down!). To see basic details on the 'service user' account right click on 
  'My Computer' and select 'Manage' or go to: Control Panel -> Administrative Tools -> 
  Computer Management -> System Tools -> Local Users and Groups.

If installed successfully, the PostgreSQL server will run in the background each time 
the system as started as a Windows service. When finished, the installer should launch 
the Application Stack Builder (ASB) (which may be used to install PostGIS, see instructions
below). A 'PostgreSQL 8.3' start menu group should be created that contains shortcuts
for the ASB and 'Command Prompt', which launches a terminal window in the PostgreSQL 
directory.

__ http://wwwmaster.postgresql.org/download/mirrors-ftp?file=%2Fbinary%2Fv8.3.3%2Fwin32%2Fpostgresql-8.3.3-2.zip

PostGIS
^^^^^^^

Launch the Application Stack Builder (Programs -> PostgreSQL 8.3), and select 
'PostgreSQL Database Server 8.3 on port 5432' from the drop down menu. Next, 
select 'PostGIS 1.3.3 for PostgreSQL 8.3' from the 'Spatial Extensions' tree
in the list. Select only the default options during install (do not uncheck 
the option to create a default PostGIS database).

.. note::

  You will be prompted to enter your 'postgres superuser' password in the 
  'Database Connection Information' dialog.

psycopg2
^^^^^^^^

The ``psycopg2`` Python module provides the interface between Python and the
PostgreSQL database. Download the `Windows installer`__ (v2.0.8) and run 
using the default settings. [#]_

__ http://www.stickpeople.com/projects/python/win-psycopg/psycopg2-2.0.8.win32-py2.5-pg8.3.3-release.exe

GeoDjango Installer
^^^^^^^^^^^^^^^^^^^

Download the `GeoDjango Installer`__; this was created [#]_ to simplify the rest
of the process for installing GeoDjango on Windows platforms. The installer
automatically installs Django 1.0, GDAL 1.5.0, PROJ.4, and configures the 
necessary enviornment variables.

Once the installer has completed, log out and log back in so that the 
modifications to the system environment variables take effect, and you
should be good to go.

.. note:

  The installer modifies the system ``Path`` environment variable to
  include ``C:\Program Files\PostgreSQL\8.3\bin`` and 
  ``C:\Program Files\GeoDjango\bin``. This is required so that Python
  may find the GEOS DLL provided by PostGIS and the GDAL DLL provided
  by the installer. The installer also sets the ``GDAL_DATA`` and 
  ``PROJ_LIB`` enviornment variables.

__ http://geodjango.org/windows/GeoDjango_Installer.exe

.. 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) <http://spatialreference.org/ref/epsg/900913/proj4>`_ 
  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>`_.
.. [#] GeoDjango uses the `find_library <http://docs.python.org/library/ctypes.html#finding-shared-libraries>`_
  routine from ``ctypes.util`` to locate shared libraries. 
.. [#] Xcode may be downloaded from the `Apple Developer Connection <http://developer.apple.com/tools/xcode/>`_ 
  or on your Mac OS X installation CDs/DVD.
.. [#] The ``psycopg2`` Windows installers are packaged and maintained by 
  `Jason Erickson <http://www.stickpeople.com/projects/python/win-psycopg/>`_. 
.. [#] The source code for the installer is available in the `nsis_installer <http://geodjango.org/hg/nsis_installer/>`_ 
  GeoDjango mercurial repository.