
##############################
FDB Installation Guide
##############################

Dependencies
************

FDB 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 FDB's
dependencies (see the download links below).


#. Operating System - one of:

    + Windows (32/64)
    + Linux Any Cpu (Known to work fine on both x86 and x86-64.)
    + Other Unix or Unix-like operating system (Macosx)

#. `Firebird <http://www.firebirdsql.org>`__ 2.0 or later - client or server 
   installation [`download here <http://sourceforge.net/project/showfiles.php?group_id=9028>`__]
#. `Python <http://www.python.org>`__ [`download here
   <http://www.python.org/download/>`__] 2.5 or later (including Python 3.x) It was tested with CPython

Installation from binary distribution
*************************************

Note: If a binary distribution of FDB (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 FDB for Windows come in the form of a
conventional executable installer or MSI package. Just invoke the installer and
follow the wizard prompts.

Because FDB 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 FDB 
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 FDB 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 FDB 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 FDB into *temp_dir*)
  cd *temp_dir*
  python setup.py build
  python setup.py install
  python -c "import fdb"
  (delete *temp_dir*)

Then hit the `Usage Guide <usage.html>`__.

Compile FDB
===================

You will need a C compiler for that. VC or MinGW to compile FDB
on Windows, and GCC to compile it on Linux/POSIX.

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

FDB 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 fdb 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
2.x and MinGW , :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 FDB 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 |
|                      |     FDB 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 FDB.                                             |
|                      |                                                                      |
|                      | 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 FDB source distribution. Try downloading the                |
|                      | FDB 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 `FDB 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 FDB:
           :command:`python setup.py build`

    + `MinGW <http://mingw.org>`__ (Windows port of GCC) 

        #. Make sure that the :file:`bin` subdirectory of the directory where you
           installed MinGW is in your PATH. FDB 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

           FDB'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 FDB,
           run the command: :command:`python setup.py build --compiler=mingw32`



Install FDB
===================

During this step, the setup script moves the FDB 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 fdb` 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 FDB, 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}/fdb` 
    (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 FDB installation
**********************************

FDB has an extensive test suite, but it is not really intended for
routine public use.

To verify that FDB 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 fdb in that directory and the copy placed under the
standard Python `site-packages` directory), then verify the
importability of your FDB installation by issuing the
following command::

  python -c "import fdb as fb; print fb.__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 FDB 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 `FDB support list 
<http://www.firebirdsql.org/index.php?op=lists#firebird-python>`__.


