##############################
KInterbasDB Installation Guide
##############################
Dependencies
************
KInterbasDB 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.
Satisfying the dependencies is not difficult! For mainstream
operating systems -- including Windows and Linux -- easily installable
binary distributions are available for *all* of KInterbasDB's
dependencies (see the download links below).
#. Operating System - one of:
+ Win32 (NT 4, 2000, XP, 2003, ...)
+ Win64 (Should work fine, but no binary distributions are available.)
+ Linux (Known to work fine on both x86 and x86-64.)
+ Other Unix or Unix-like operating system
#. `Firebird <http://www.firebirdsql.org>`__ 2.0 or later - client or server
installation [`download here <http://sourceforge.net/project/showfiles.php?group_id=9028>`__]
If you want to use KInterbasDB 3.3 with Firebird 1.5 and older or InterBase, you
will need to do `installation from source distribution`_ instead.
#. `Python <http://www.python.org>`__ [`download here
<http://www.python.org/download/>`__] 2.4 or later
#. `eGenix.com mx Extensions for Python
<http://www.lemburg.com/files/python/eGenix-mx-Extensions.html>`__,
version 2.0.1 or later [`download here
<http://www.lemburg.com/files/python/eGenix-mx-Extensions.html
#Download-mxBASE>`__] By default, KInterbasDB uses the `DateTime`
module of the eGenix.com `mx` Extensions to represent date and time
values, as recommended by the
*Python Database API Specification*. *However, it is not strictly necessary
to use the `mx.DateTime` module to handle dates and times, especially when you're
using Python 2.5 and newer.* See `this
FAQ <usage.html#faq_fep_is_mxdatetime_required>`__.
Installation from binary distribution
*************************************
Note: If a binary distribution of KInterbasDB (e.g., a Windows
executable installer) is not available for your platform, Python or Firebird
version, you will need to do `installation from source distribution`_ instead.
Windows
=======
Binary distributions of KInterbasDB for Windows come in the form of a
conventional executable installer or MSI package. Just invoke the installer and
follow the wizard prompts.
Because KInterbasDB is compatible with numerous versions of Python,
you must choose a binary distribution that matches your Python version.
There are currently Windows binary distributions of KInterbasDB
compiled for use with Firebird 2.x for each of Python 2.4, 2.5 and 2.6.
Linux and Other Unix Variants
=============================
Currently, Linux users must typically install from `source distribution`_
as only Mandriva Linux offer the pre-built KInterbasDB package.
The source distribution will *probably* also install (and function) on most
other POSIX-compliant Unix variants, as long as all of the dependencies_
are also installed and functional.
Because the KInterbasDB source distribution supports the standard
Python package installation facility (`distutils
<http://www.python.org/sigs/distutils-sig/>`__), installing the source
distribution on a typical Linux system is downright easy.
.. _`source distribution`:
Installation from source distribution
*************************************
Shortcut for the Experienced and Impatient::
(decompress KInterbasDB into *temp_dir*)
cd *temp_dir*
python setup.py build
python setup.py install
python -c "import kinterbasdb"
(delete *temp_dir*)
Then hit the `Usage Guide <usage.html>`__.
Compile KInterbasDB
===================
You will need a C compiler for that. VC or MinGW to compile KInterbasDB
on Windows, and GCC to compile it on Linux/POSIX.
Once you have successfully installed the dependencies, you may proceed
with the installation of KInterbasDB itself.
Beginning with version 3.0, KInterbasDB has full support for the
`distutils <http://www.python.org/sigs/distutils-sig/>`__, the
standard facility for Python package distribution and installation.
Full instructions for using the distutils are available `here
<http://www.python.org/doc/current/inst/inst.html>`__, but you can
skip them unless you have an otherwise insoluble problem.
Open a command prompt, change to the directory where you decompressed
the kinterbasdb source distribution, and type::
python setup.py build
The installation script, :file:`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) or record their
locations in the system registry (on Windows), the compilation should
proceed without incident.
On Windows, compilers other than Microsoft Visual C++ usually require
some library conversion to work with Python or Firebird. With Firebird
1.5 and MinGW or Firebird 1.0 and Borland C++, :file:`setup.py` will perform
this conversion automatically. If the automatic conversion fails,
ensure that your compiler is installed properly (especially that its
:file:`bin` directory is in your :file:`PATH`). For more information, see
thecompiler-specific notes in this document, as well as the Python standard
library documentation on "Installing Python Modules".
If :file:`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, examine its contents and then consult
the following table:
+----------------------+----------------------------------------------------------------------+
| Error Message Header | Explanation |
+======================+======================================================================+
| **LIBRARY | The setup script was unable to automatically find one or more files |
| AUTODETECTION ERROR**| needed for the compilation process, such as a library needed by the |
| | C compiler. |
| | |
| | Using a text editor, you will need to manually specify the relevant |
| | paths in the `manual_config` section of the setup configuration file,|
| | :file:`setup.cfg` (in the root directory of the KInterbasDB source |
| | distribution). Uncomment the item in question and provide a value |
| | appropriate to your system. Save the newly modified |
| | :file:`setup.cfg`, then repeat the compilation step. |
| | |
| | If manually specifying the library paths fails to solve the problem: |
| | - Your C compiler or linker may not be properly configured. |
| | - You may have a corrupt or incomplete installation of one or more |
| | KInterbasDB dependencies. |
| +----------------------------------------------------------------------+
| | *Note for non-Windows platforms:* |
| | If the compiler indicates that it cannot find the include file |
| | :file:`Python.h`, this probably means that you have the user-oriented|
| | Python package installed, but not the developer-oriented package that|
| | would enable you to compile C extensions. |
| | |
| | For example, RedHat-derived distributions such as Fedora split the |
| | core Python distribution into :file:`python-{x.y.z}`, :file:`python- |
| | devel-{x.y.z}` and :file:`python-docs-{x.y.z}` packages. |
| | You'll need to install the :file:`python-devel-{x.y.z}` package |
| | in order to compile KInterbasDB. |
| | |
| | The use of C extensions to Python is quite common, so Python |
| | repackagers such as Linux distributions should include the files |
| | necessary to compile C extensions in their basic Python package. The |
| | Python core developers have noticed these repackaging mistakes and |
| | complained about them, but apparently without effect. |
+----------------------+----------------------------------------------------------------------+
| **COMPILER | The setup script could not function because of the current |
| CONFIGURATION ERROR**| configuration of your compiler. The error message should provide |
| | details about what went wrong, and perhaps a suggestion of how to fix|
| | the problem. |
| | |
| | If you are not using the standard compiler for your platform, consult|
| | the compiler-specific notes. |
+----------------------+----------------------------------------------------------------------+
| **LIBRARY CONVERSION | The setup script's attempt to convert libraries intended for use with|
| ERROR** | Microsoft Visual C++ into a format compatible with your compiler was |
| | not successful. |
| | |
| | Consult the compiler-specific notes in this document, as well as the |
| | Python standard library documentation on "Installing Python Modules".|
+----------------------+----------------------------------------------------------------------+
| **PYTHON SYSTEM | Your Python installation is outdated, lacks some crucial modules, or |
| ERROR** | is otherwise inadequate. The error message will indicate what your |
| | options are, which may include installing a more recent Python |
| | version, compiling additional C extension modules for your current |
| | Python version, or editing :file:`setup.cfg` to manually specify |
| | library paths, thus relieving :file:`setup.py` of the burden |
| | of detecting them. |
+----------------------+----------------------------------------------------------------------+
| **KINTERBASDB | The setup script cannot find a file that was supposed to be included |
| DISTRIBUTION ERROR** | with the KInterbasDB source distribution. Try downloading the |
| | KInterbasDB source distribution again and decompressing it into a |
| | fresh temporary directory, then repeat the compilation step. |
+----------------------+----------------------------------------------------------------------+
| **LIBRARY MANUAL | One of the library paths specified in :file:`setup.cfg` is not valid.|
| SPECIFICATION ERROR**| Verify the location of the library, then edit :file:`setup.cfg` to |
| | reflect the correct path. |
| | |
| | If you had no particular reason to manually specify the library path |
| | in the first place, try commenting out that entry in |
| | :file:`setup.cfg`, then repeat the compilation step and let the setup|
| | script attempt to automatically detect the location of the library. |
+----------------------+----------------------------------------------------------------------+
If the problem persists after you have followed the advice in the
error message itself and in the table above, visit the `KInterbasDB support list
<http://www.firebirdsql.org/index.php?op=lists#firebird-python>`__ and report your problem.
Compiler-Specific Notes
-----------------------
+ Microsoft Windows
+ Microsoft Visual C++ 6.0
#. The Visual C++ command-line utilities must be available on your
system path, and their required environment variables must be
initialized to meaningful values. If, when you installed Visual C++,
you did *not* allow it to register the paths needed for command-line
compilation, you will need to run the :file:`vcvars32.bat` batch file from
the :file:`bin` subdirectory of your Visual C++ installation. By default,
this directory is :file:`C:\\Program Files\\Microsoft Visual Studio\\VC98\\bin`
#. Use the * same * command prompt window to run the following command
in the temporary directory into which you decompressed KInterbasDB:
:command:`python setup.py build`
+ `MinGW <http://mingw.org>`__ (Windows port of GCC) Note that
KInterbasDB supports MinGW only with Firebird 1.5 or later, not
Firebird 1.0 or Interbase®. With earlier versions of the database,
use Microsoft Visual C++.
#. Make sure that the :file:`bin` subdirectory of the directory where you
installed MinGW is in your PATH. KInterbasDB requires numerous MinGW
sub-packages, so it's easiest to install the monolithic distribution
of MinGW, rather than piecing together individual sub-packages. The
monolithic distribution is an executable installer; installation is
trivial. If you do decide to install individual MinGW sub-packages,
you must install at least the following:
+ binutils
+ gcc-core
+ mingw-runtime
+ mingw-utils
+ w32api
KInterbasDB's setup script will automatically perform all of the
required preparatory steps for compiling an extension with MinGW on
your Python installation.
#. In the temporary directory into which you decompressed KInterbasDB,
run the command: :command:`python setup.py build --compiler=mingw32`
Install KInterbasDB
===================
During this step, the setup script moves the KInterbasDB package
(including the newly compiled C extensions) to the standard package
directory of your Python installation so that Python will be able to
:command:`import kinterbasdb` and :command:`import kinterbasdb.services`
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:
:command:`python setup.py install`
The setup script will install KInterbasDB, 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
repeatthe installation step.
- Manually copy the directory :file:`build/lib.{platform}-{pyver}/kinterbasdb`
(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.
Test your KInterbasDB installation
**********************************
KInterbasDB has an extensive test suite, but it is not really intended for
routine public use.
To verify that KInterbasDB is installed properly, switch to a
directory *other than the temporary directory into which you
decompressed the source distribution* (to avoid conflict between the
copy of kinterbasdb in that directory and the copy placed under the
standard Python `site-packages` directory), then verify the
importability of your KInterbasDB installation by issuing the
following command::
python -c "import kinterbasdb as k; print k.__version__"
If the import attempt does not encounter any errors and the version
number is what you expected, you are finished. Next, consider reading
the KInterbasDB Usage Guide.
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 `KInterbasDB support list
<http://www.firebirdsql.org/index.php?op=lists#firebird-python>`__.
