---------------------------------------------------------------
pysqlite installation guide - installing from source on Windows
---------------------------------------------------------------

\(c\) 2005 Gerhard Häring

Steps:

  - `Step 1: Download and install required tools`_
  - `Step 2: Download and compile SQLite`_
  - `Step 3: Compile pysqlite`_
  - `Step 4: Install pysqlite or create an installer`_
  - `Step 5: Test your pysqlite installation`_

Step 1: Download and install required tools
===========================================

This guide explains how to build SQLite and pysqlite with free and commercial
Microsoft compilers for Python 2.4 and later. Other compilers might work, too,
and MINGW is known to work well for Python 2.3, but in order to keep this
document to the point, only one obvious way to do it is documented.

First we need to have a working compiler. These two work fine:

    * Microsoft Visual Studio .NET 2003
    * MS Toolkit Compiler (http://www.vrplumber.com/programming/mstoolkit/)

Then, we need GNU make. Download a Windows version from
http://mingw.sourceforge.net/download.shtml and extract it.

Make sure your PATH is set up correctly, so that the make.exe you just
downloaded is in the PATH and that your compiler's environment is set up
correctly. For MS Visual Studio .NET 2003, just execute
Start/Programs/Microsoft Visual Studio .NET/Visual Studio .NET Tools/Visual
Studio .NET 2003 Command Prompt. For the MS Toolkit Compiler write yourself a
batch file that sets up the environment as neccessary.

Step 2: Download and compile SQLite
===================================

From now on, let's suppose you do all your development work in $SRCDIR.

Now download the latest versions of the SQLite 3.x Windows sources from http://sqlite.org/download.html.

Pick the download that looks like this:

sqlite-source-3_{major}_{minor}.zip

Extract this file in $SRCDIR/sqlite

Now copy this file into your $SRCDIR/sqlite directory:
http://initd.org/svn/pysqlite/pysqlite/trunk/misc/Makefile

Then on a Windows command prompt, change into the $SRCDIR/sqlite directory and
issue a "make". This should build a statically linked SQLite library now::

    Setting environment for using Microsoft Visual Studio .NET 2003 tools.
    (If you have another version of Visual Studio or Visual C++ installed and wish
    to use its tools from the command line, run vcvars32.bat for that version.)

    C:\Documents and Settings\Gerhard>set path=c:\msys\1.0\bin;%PATH%

    C:\Documents and Settings\Gerhard>d:

    D:\>cd src\sqlite

    D:\src\sqlite>make
    cl -c -O2 -Og -G7 -Foalter.o alter.c
    Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 13.10.3077 for 80x86
    Copyright (C) Microsoft Corporation 1984-2002. All rights reserved.

    alter.c
    cl -c -O2 -Og -G7 -Foanalyze.o analyze.c
    Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 13.10.3077 for 80x86
    Copyright (C) Microsoft Corporation 1984-2002. All rights reserved.

    [...]

    utf.c
    cl -c -O2 -Og -G7 -Folegacy.o legacy.c
    Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 13.10.3077 for 80x86
    Copyright (C) Microsoft Corporation 1984-2002. All rights reserved.

    legacy.c
    link -LIB -OUT:sqlite3.lib alter.o analyze.o attach.o auth.o btree.o build.o cal
    lback.o complete.o date.o delete.o expr.o func.o hash.o insert.o main.o opcodes.
    o os_unix.o os_win.o pager.o parse.o pragma.o prepare.o printf.o random.o select
    .o table.o tokenize.o trigger.o update.o util.o vacuum.o vdbe.o vdbeapi.o vdbeau
    x.o vdbefifo.o vdbemem.o where.o utf.o legacy.o
    Microsoft (R) Library Manager Version 7.10.3077
    Copyright (C) Microsoft Corporation.  All rights reserved.

    done

    D:\src\sqlite>


Step 3: Compile pysqlite
========================

Unpack the latest pysqlite sources in $SRCDIR/pysqlite

Now change the include_dirs and library_dirs settings in ``setup.cfg`` like
this::

    [build_ext]
    define=
    include_dirs=../sqlite
    library_dirs=../sqlite
    libraries=sqlite3

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

  python setup.py build

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 4: Install pysqlite or create an installer
===============================================

To install pysqlite now, invoke::

    python setup.py install

from the commandline. In order to create an installer executable, invoke::

    python setup.py bdist_wininst

from the commandline.

Step 5: 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 151 tests in 1.059s

    OK
    >>>

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/
.. _pysqlite bug tracker: http://initd.org/tracker/pysqlite
.. _pysqlite mailing list: http://lists.initd.org/mailman/listinfo/pysqlite
