KInterbasDB Installation Guide — KInterbasDB v3.3.0 documentation

### Navigation

- index
- modules |
- next |
- previous |
- KInterbasDB v3.3.0 documentation »

# 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).

1. 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

2. Firebird 2.0 or later - client or server installation [download here] 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.

3. Python [download here] 2.4 or later

4. eGenix.com mx Extensions for Python, version 2.0.1 or later [download here] 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.

## 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), installing the source distribution on a typical Linux system is downright easy.

## 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.

### 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, the standard facility for Python package distribution and installation. Full instructions for using the distutils are available here, 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, `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++, `setup.py` will perform this conversion automatically. If the automatic conversion fails, ensure that your compiler is installed properly (especially that its `bin` directory is in your `PATH`). For more information, see thecompiler-specific notes in this document, as well as the Python standard library documentation on “Installing Python Modules”.

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, examine its contents and then consult the following table:

Error Message Header | Explanation
--- | ---
LIBRARY AUTODETECTION ERROR | The setup script was unable to automatically find one or more files 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, `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 `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 `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 `python-x.y.z`, `python- devel-x.y.z` and `python-docs-x.y.z` packages. You’ll need to install the `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 CONFIGURATION ERROR | The setup script could not function because of the current 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 ERROR | The setup script’s attempt to convert libraries intended for use with 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 ERROR | Your Python installation is outdated, lacks some crucial modules, or 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 `setup.cfg` to manually specify library paths, thus relieving `setup.py` of the burden of detecting them.
KINTERBASDB DISTRIBUTION ERROR | The setup script cannot find a file that was supposed to be included 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 SPECIFICATION ERROR | One of the library paths specified in `setup.cfg` is not valid. Verify the location of the library, then edit `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 `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 and report your problem.

#### Compiler-Specific Notes

- Microsoft Windows

  > - Microsoft Visual C++ 6.0

  >   > 1. 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 `vcvars32.bat` batch file from the `bin` subdirectory of your Visual C++ installation. By default, this directory is `C:\Program Files\Microsoft Visual Studio\VC98\bin`
  >   > 2. Use the * same * command prompt window to run the following command in the temporary directory into which you decompressed KInterbasDB: python setup.py build

  > - MinGW (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++.

  >   > 1. Make sure that the `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.

  >   > 2. In the temporary directory into which you decompressed KInterbasDB, run the 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 import kinterbasdb and 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: 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 `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.

### Navigation

- index
- modules |
- next |
- previous |
- KInterbasDB v3.3.0 documentation »