                     SIP - Python/C++ Bindings Generator


INTRODUCTION

SIP is a tool for generating bindings for C and C++ libraries so that they can
be accessed as normal Python classes.  SIP takes many of its ideas from SWIG
but, because it is specifically designed for Python, is able to generate
tighter bindings.  SIP is so called because it originally started out as a
small SWIG.

SIP was originally designed to generate Python bindings for Qt and so has
explicit support for Qt's signal slot mechanism.  However, SIP can be used to
generate Python bindings for any C or C++ library.

The bindings generated by SIP support access to the following C++ and Qt
features:
	- connecting Qt signals to Python functions and class methods
	- connecting Python signals to Qt slots
	- overloading virtual member functions with Python class methods
	- protected member functions
	- abstract classes
	- enumerated types
	- global class instances
	- static member functions.

This package comprises the SIP binary that generates the C/C++ code, a header
file that is needed to compile the generated C/C++ code, a binary Python module
that is needed by any set of compiled bindings, and a pure Python module that
can be used by configuration scripts.

The homepage of SIP is http://www.riverbankcomputing.co.uk/sip/.

SIP is available under a number of licenses.  See the LICENSE file for the
license under which this copy is provided.


INSTALLATION

Check for any other README files in this directory that relate to your
particular platform.  Feel free to contribute a README for your platform or to
provide updates to any existing documentation.

The first step is to configure SIP by running the following command.

	python configure.py

This assumes that the correct Python interpreter is on your path.  Something
like the following may be appropriate on Windows.

	c:\python23\python configure.py

If you have multiple versions of Python installed then make sure you use the
interpreter for which you wish SIP to generate bindings for.

Qt support is automatically enabled if the QTDIR environment variable is set.
Use the "-x" command line option to disable it.

The configure.py script takes many options that allows the build system to be
finely tuned.  Use the "-h" command line options to display a full list of the
available options.  For example, the following will generate smaller modules
using GCC.

	python configure.py "CXXFLAGS+=-fno-exceptions -fno-rtti" LFLAGS+=-s

The next step is to build SIP using your platform's make command.

	make

The final step is to install SIP by running the following command.  (Depending
on your system you may require root or administrator privileges.)

	make install

Note that this method of installation is relatively new.  If you experience
problems than please send a bug report and try the old method described below.


INSTALLATION - THE OLD WAY

This is the deprecated method of building SIP.  It will be removed once the
new way, described above, has proved itself to be stable.

This method uses either "tmake" or "qmake" to actually generate the required
Makefiles.  "qmake" is provided with Qt v3.x.  If you are using an earlier
version of Qt then you will need a copy of "tmake" (v1.8 or later) which is
available from Trolltech (http://www.trolltech.com).  You will need to
configure "tmake" for your system by setting the TMAKEPATH environment variable
to an appropriate value - see the "tmake" documentation for the details.

First of all, run the `build.py' Python script.  If you have multiple versions
of Python installed then make sure you use the interpreter for which you wish
SIP to generate bindings for.  The build script generates all the relevant
makefiles.  The script takes a number of options that allows you to override
particular settings.  Run "python build.py -h" to get a list of the available
options.

Compiling and installing SIP is then a simple case of running "make" followed
by "make install".  Note that on a system where you would normally only need
administrator privileges to install SIP, you also need them to compile SIP.


Phil Thompson
phil@riverbankcomputing.co.uk
