Document how to use spatialite with homebrew

[Kenial Sookyum Lee]

Installing libspatialite package with Homebrew on OS X and using django.contrib.gis.db.backends.spatialite as a database backend, I met this exception (using Homebrew 0.9.5, checked on OS X 10.10.1 and OS X 10.8.5) :

Traceback (most recent call last):
  File "manage.py", line 14, in <module>
    execute_from_command_line(sys.argv)
  File "/Users/kenial/.virtualenvs/fp/lib/python2.7/site-packages/django/core/management/__init__.py", line 385, in execute_from_command_line
    utility.execute()
  File "/Users/kenial/.virtualenvs/fp/lib/python2.7/site-packages/django/core/management/__init__.py", line 377, in execute
    self.fetch_command(subcommand).run_from_argv(self.argv)
  File "/Users/kenial/.virtualenvs/fp/lib/python2.7/site-packages/django/core/management/base.py", line 288, in run_from_argv
    self.execute(*args, **options.__dict__)
  File "/Users/kenial/.virtualenvs/fp/lib/python2.7/site-packages/django/core/management/base.py", line 338, in execute
    output = self.handle(*args, **options)
  File "/Users/kenial/.virtualenvs/fp/lib/python2.7/site-packages/django/core/management/commands/migrate.py", line 63, in handle
    executor = MigrationExecutor(connection, self.migration_progress_callback)
  File "/Users/kenial/.virtualenvs/fp/lib/python2.7/site-packages/django/db/migrations/executor.py", line 17, in __init__
    self.loader = MigrationLoader(self.connection)
  File "/Users/kenial/.virtualenvs/fp/lib/python2.7/site-packages/django/db/migrations/loader.py", line 48, in __init__
    self.build_graph()
  File "/Users/kenial/.virtualenvs/fp/lib/python2.7/site-packages/django/db/migrations/loader.py", line 179, in build_graph
    self.applied_migrations = recorder.applied_migrations()
  File "/Users/kenial/.virtualenvs/fp/lib/python2.7/site-packages/django/db/migrations/recorder.py", line 59, in applied_migrations
    self.ensure_schema()
  File "/Users/kenial/.virtualenvs/fp/lib/python2.7/site-packages/django/db/migrations/recorder.py", line 49, in ensure_schema
    if self.Migration._meta.db_table in self.connection.introspection.get_table_list(self.connection.cursor()):
  File "/Users/kenial/.virtualenvs/fp/lib/python2.7/site-packages/django/db/backends/__init__.py", line 165, in cursor
    cursor = self.make_debug_cursor(self._cursor())
  File "/Users/kenial/.virtualenvs/fp/lib/python2.7/site-packages/django/db/backends/__init__.py", line 138, in _cursor
    self.ensure_connection()
  File "/Users/kenial/.virtualenvs/fp/lib/python2.7/site-packages/django/db/backends/__init__.py", line 133, in ensure_connection
    self.connect()
  File "/Users/kenial/.virtualenvs/fp/lib/python2.7/site-packages/django/db/backends/__init__.py", line 122, in connect
    self.connection = self.get_new_connection(conn_params)
  File "/Users/kenial/.virtualenvs/fp/lib/python2.7/site-packages/django/contrib/gis/db/backends/spatialite/base.py", line 65, in get_new_connection
    six.reraise(ImproperlyConfigured, ImproperlyConfigured(new_msg), sys.exc_info()[2])
  File "/Users/kenial/.virtualenvs/fp/lib/python2.7/site-packages/django/contrib/gis/db/backends/spatialite/base.py", line 60, in get_new_connection
    cur.execute("SELECT load_extension(%s)", (self.spatialite_lib,))
  File "/Users/kenial/.virtualenvs/fp/lib/python2.7/site-packages/django/db/backends/sqlite3/base.py", line 485, in execute
    return Database.Cursor.execute(self, query, params)
django.core.exceptions.ImproperlyConfigured: Unable to load the SpatiaLite library extension "/usr/local/lib/libspatialite.dylib" because: dlsym(0x7f8bf32f8000, sqlite3_spatialite_init): symbol not found

On Homebrew's SpatiaLite 4.2.0 package what I've got, it provides both libspatialite.7.dylib and mod_spatialite.7.dylib. For its proper working, sqlite3 should load mod_spatialite instead of libspatialite, but it seems not detecting right package with ctypes.util.find_library('spatialite'). In case using find_library('mod_spatialite'), it does work.

I think it might be a problem of entry point, however, the sqlite3_spatialite_init symbol is in mod_spatialite.7.dylib at least, for it works.

p.s: For sure, you can avoid this by declaring sptialite library path manually in settings.py, like as:

SPATIALITE_LIBRARY_PATH='/usr/local/lib/mod_spatialite.dylib'

[Kenial Sookyum Lee]

patch of Ticket #23901

[Tim Graham]

I think it'd probably be better to include a note in the documentation about this (suggest using the setting) rather than hardcoding a workaround in Django for what appears to be a non-standard library name.

[Kenial Sookyum Lee]

Agreed. But I have no idea where I begin to work on - for this is my first contributing on django - , may I ask you few questions?

• I think this document url is right position to start, you know, it's sort of outdated. Is it better to leave contents for older version (KyngChaos packages and its SpatiaLite version is 2.3.1, current SpatiaLite version supported by Homebrew is 4.2.0), or get rid of them? What do you think?

​https://docs.djangoproject.com/en/1.7/ref/contrib/gis/install/spatialite/#spatialite-macosx

• How can I post updated document? Just pull requests in same way with codes? (specifically, commiting to path /docs on Django repo)

[Tim Graham]

Some updates to the Mac OS X instructions would be welcome. We can likely remove the older out-of-date information.

Yes, contributing to the docs is the same process as making code changes.

[Kenial Sookyum Lee]

Okay, I'll get to it soon. Thanks!

[Kenial Sookyum Lee]

Posted a GitHub pull request.

[Tim Graham <timograham@…>]

In cc870b8ef5e3464c6f051e3ef0a25dfc4b597452:

Fixed #23901 -- Documented how to use SpatiaLite with Homebrew.

[Tim Graham <timograham@…>]

In 5f79da581440dba6275f70e8a6ef440a32dbb895:

[1.7.x] Fixed #23901 -- Documented how to use SpatiaLite with Homebrew.

Backport of cc870b8ef5e3464c6f051e3ef0a25dfc4b597452 from master