-------------------------------------------------
pysqlite installation guide - source distribution
-------------------------------------------------

\(c\) 2005 Gerhard Häring

Note: For Windows users, it is recommended that you use the win32 binary
  distribution of pysqlite!

Steps:

  - `Step 1: Satisfy the dependencies`_
  - `Step 2: Compile pysqlite`_
  - `Step 3: Install pysqlite`_
  - `Step 4: Test your pysqlite installation`_

Step 1: Satisfy The Dependencies
================================

pysqlite requires a valid combination of the dependencies in the list below.

Detailed instructions on how to install each dependency are beyond the scope of
this document; consult the dependency distributor for installation
instructions.

Dependencies:

 1. Operating System and C Compiler - one of:

    * Linux/FreeBSD/NetBSD/OpenBSD and GCC

    * Other POSIX-compliant operating system and a C compiler

 2. SQLite:

    * SQLite version 3.0.8 or later (as of pysqlite 2.2.0). This means we need
      the SQLite library installed - either statically or dynamically linked -
      and the SQLite header files. On Linux, the chances are very high that
      your distribution offers packages for SQLite 3. Be sure to verify the
      package is recent enough (version 3.0.8 or higher) and that you're
      installing the development package as well, which will be need for
      building pysqlite. On Debian and derivatives, the package to look for is
      called libsqlite3-dev.

 3. Python:

    * Python 2.3 or later

Step 2: Compile pysqlite
========================

Once you have successfully installed the dependencies, you may proceed with the
installation of pysqlite itself.

pysqlite has full support for the distutils_, the standard facility for Python
package distribution and installation. Full instructions for using the
distutils are available in `this section of the Python documentation`_, but you
can skip them unless you have an otherwise insoluble problem.

Open a command prompt, change to the directory where you decompressed the
pysqlite source distribution, and type::

  python setup.py build

The installation script, setup.py, will attempt to automatically detect the
information needed by the C compiler; then it will invoke the distutils to
perform the actual compilation. If you installed automatic distributions of the
dependencies that place themselves in standard locations (on UNIX-style
operating systems), the compilation should proceed without incident.

Otherwise you will have to customize the build process. That's what the file
*setup.cfg* is meant for. It's contains a few lines that you can customize so
your C compiler will find the library and header files and you can also do a
few other tweaks, like build pysqlite in debug mode.

After you've customized *setup.cfg* appropriately, try invoking ``python
setup.py build`` again.

If setup.py raises no errors and its output concludes with something like
"Creating library...", then you are ready to proceed to the next step.

If you receive an error message from the compiler, then try to look at the
first error it reports. Other errors will most likely be aftereffects from the
first error (like not finding the sqlite3.h header file).


Step 3: Install pysqlite
========================

During this step, the setup script moves the *pysqlite2* package (including the
newly compiled C extension) to the standard package directory of your Python
installation so that Python will be able to import pysqlite2.dbapi2 and
pysqlite2.test.

In addition to the Python code and shared library files actually used by the
Python interpreter, the setup script typically installs some supporting files,
such as documentation. Depending on your system configuration, these supporting
files may be placed in the same directory or a different directory from the
files used by the Python interpreter.

Run the following command::

  python setup.py install

The setup script will install pysqlite, listing each file it installs.

Errors during this step are rare because compilation (the finicky part of this
process) has already taken place; installation is really just a matter of
copying files. However, there will be file system permission errors if the
Python installation directory is not writable by the user running the setup
script. If you encounter such an error, try one of the following:

- Log in as a user who has the required file system permissions and repeat the
  installation step.
- Manually copy the directory build/lib.platform-pyver/pysqlite2 (which
  contains the Python modules and compiled library files created during the
  compilation step) to a directory in your PYTHONPATH. This approach will not
  install the supporting files, but they are for the benefit of the programmer
  rather than the Python interpreter anyway. 

Step 4: Test Your pysqlite Installation
=======================================

Switch to a directory other than the temporary directory into which you
decompressed the source distribution (to avoid conflict between the copy of
pysqlite in that directory and the copy placed under the standard Python
site-packages directory), then run the pysqlite test suite by starting a Python
interpreter for the Python version you installed pysqlite for and entering the
following::

    >>> from pysqlite2 import test
    >>> test.test()
    .....................................................................................................
    ----------------------------------------------------------------------
    Ran 101 tests in 0.182s

If the test suite runs without any errors, you are finished.

You should not encounter any errors at this stage since you have already
completed the compilation and installation steps successfully. If you do,
please report them to the `pysqlite bug tracker`_ or the `pysqlite mailing
list`_.

.. _distutils: http://www.python.org/sigs/distutils-sig/
.. _this section of the Python documentation: http://www.python.org/doc/current/inst/inst.html
.. _pysqlite bug tracker: http://pysqlite.googlecode.com/
.. _pysqlite mailing list: http://itsystementwicklung.de/cgi-bin/mailman/listinfo/list-pysqlite