<commit_before>===============================
Installing Geospatial libraries
===============================

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

========================  ====================================  ================================  ==========================
Program                   Description                           Required                          Supported Versions
========================  ====================================  ================================  ==========================
:doc:`GEOS <../geos>`     Geometry Engine Open Source           Yes                               3.4, 3.3, 3.2
`PROJ.4`_                 Cartographic Projections library      Yes (PostgreSQL and SQLite only)  4.8, 4.7, 4.6, 4.5, 4.4
:doc:`GDAL <../gdal>`     Geospatial Data Abstraction Library   Yes (SQLite only)                 1.10, 1.9, 1.8, 1.7
:doc:`GeoIP <../geoip>`   IP-based geolocation library          No                                1.4
`PostGIS`__               Spatial extensions for PostgreSQL     Yes (PostgreSQL only)             2.1, 2.0, 1.5
`SpatiaLite`__            Spatial extensions for SQLite         Yes (SQLite only)                 4.1, 4.0, 3.0, 2.4
========================  ====================================  ================================  ==========================

Note that older or more recent versions of these libraries *may* also work
totally fine with GeoDjango. Your mileage may vary.

..
    Libs release dates:
    GEOS 3.2.0 2009-12-14
    GEOS 3.3.0 2011-05-30
    GEOS 3.4.0 2013-08-11
    GDAL 1.7.1 2010-02-08
    GDAL 1.8.0 2011-01-13
    GDAL 1.9.0 2012-01-03
    GDAL 1.10.0 2013-04-29
    GDAL 1.11.0 2014-04-25 # To be tested!
    PostGIS 1.5.0 2010-02-04
    PostGIS 2.0.0 2012-04-03
    PostGIS 2.1.0 2013-08-17
    Spatialite 2.4.0 2010-11-14
    Spatialite 3.0.0 2011-12-30
    Spatialite 4.0.0 2012-11-25
    Spatialite 4.1.0 2013-06-04

.. admonition::  Install GDAL

    While :ref:`gdalbuild` is technically not required, it is *recommended*.
    Important features of GeoDjango (including the :doc:`../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.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:: console

    $ sudo apt-get install binutils libproj-dev gdal-bin

Optional packages to consider:

* ``libgeoip1``: for :doc:`GeoIP <../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.8 from the GEOS Web site and untar the source
archive::

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

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

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

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

Can't find GEOS library<commit_msg>Update link to use GEOS 3.4.2 in source installation docs.<commit_after>===============================
Installing Geospatial libraries
===============================

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

========================  ====================================  ================================  ==========================
Program                   Description                           Required                          Supported Versions
========================  ====================================  ================================  ==========================
:doc:`GEOS <../geos>`     Geometry Engine Open Source           Yes                               3.4, 3.3, 3.2
`PROJ.4`_                 Cartographic Projections library      Yes (PostgreSQL and SQLite only)  4.8, 4.7, 4.6, 4.5, 4.4
:doc:`GDAL <../gdal>`     Geospatial Data Abstraction Library   Yes (SQLite only)                 1.10, 1.9, 1.8, 1.7
:doc:`GeoIP <../geoip>`   IP-based geolocation library          No                                1.4
`PostGIS`__               Spatial extensions for PostgreSQL     Yes (PostgreSQL only)             2.1, 2.0, 1.5
`SpatiaLite`__            Spatial extensions for SQLite         Yes (SQLite only)                 4.1, 4.0, 3.0, 2.4
========================  ====================================  ================================  ==========================

Note that older or more recent versions of these libraries *may* also work
totally fine with GeoDjango. Your mileage may vary.

..
    Libs release dates:
    GEOS 3.2.0 2009-12-14
    GEOS 3.3.0 2011-05-30
    GEOS 3.4.0 2013-08-11
    GDAL 1.7.1 2010-02-08
    GDAL 1.8.0 2011-01-13
    GDAL 1.9.0 2012-01-03
    GDAL 1.10.0 2013-04-29
    GDAL 1.11.0 2014-04-25 # To be tested!
    PostGIS 1.5.0 2010-02-04
    PostGIS 2.0.0 2012-04-03
    PostGIS 2.1.0 2013-08-17
    Spatialite 2.4.0 2010-11-14
    Spatialite 3.0.0 2011-12-30
    Spatialite 4.0.0 2012-11-25
    Spatialite 4.1.0 2013-06-04

.. admonition::  Install GDAL

    While :ref:`gdalbuild` is technically not required, it is *recommended*.
    Important features of GeoDjango (including the :doc:`../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.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:: console

    $ sudo apt-get install binutils libproj-dev gdal-bin

Optional packages to consider:

* ``libgeoip1``: for :doc:`GeoIP <../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.4.2 from the GEOS Web site and untar the source
archive::

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

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

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

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

Can't find GEOS library
{'fraction_non_alphanumeric': 0.18050348152115694, 'fraction_numerical': 0.04874129619710766, 'mean_word_length': 2.885143570536829, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 16, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1445455', 'n_tokens_mistral': 3148, 'n_tokens_neox': 2684, 'n_words': 962}