1.1   License

SIP is licensed under the same terms as Python itself. SIP places no restrictions on the license you may apply to the bindings you create.

1.2   Features

SIP, and the bindings it produces, have the following features.

• bindings are fast to load and minimise memory consumption especially when only a small sub-set of a large library is being used
• automatic conversion between standard Python and C/C++ data types
• overloading of functions and methods with different argument signatures
• access to a C++ class's protected methods
• the ability to define a Python class that is a sub-class of a C++ class, including abstract C++ classes
• support for ordinary C++ functions, class methods, static class methods, virtual class methods and abstract class methods
• the ability to re-implement C++ virtual and abstract methods in Python
• support for global and class variables
• support for C++ namespaces
• support for C++ exceptions and wrapping them as Python exceptions
• the ability to define mappings between C++ classes and similar Python data types that are automatically invoked
• the ability to automatically exploit any available run time type information to ensure that the class of a Python instance object matches the class of the corresponding C++ instance
• full support of the Python interpreter lock, including the ability to specify that a C++ function of method may block, therefore allowing the lock to be released and other Python threads to run
• support for the concept of ownership of a C++ instance (i.e. what part of the code is responsible for calling the instance's destructor) and how the ownership may change during the execution of an application
• the ability to generate bindings for a C++ class library that itself is built on another C++ class library which also has had bindings generated so that the different bindings integrate and share code properly
• a sophisticated versioning system that allows the full lifetime of a C++ class library, including any platform specific or optional features, to be described in a single set of specification files
• the ability to include documentation in the specification files which can be extracted and subsequently processed by external tools
• the ability to include copyright notices and licensing information in the specification files that is automatically included in all generated source code
• a build system, written in Python, that you can extend to configure, compile and install your own bindings without worrying about platform specific issues
• SIP, and the bindings it produces, runs under UNIX, Linux, Windows and MacOS/X

SIP also understands the signal/slot type safe callback mechanism implemented by Qt. SIP allows new Python signals to be defined, and allows any Python callable object to be used as a slot.

Throughout this manual PyQt will be used as the source of examples because, often, it is PyQt's requirements that drives the implementation of new SIP features.

1.3   SIP v3.x

SIP v3.x differs from current versions in the following respects.

• It uses Python's classic classes to wrap C++ classes (and so generated bindings can be built against any version of Python).
• It does not support the creation of bindings for C libraries.
• It does not generate bindings that will work on MacOS/X.
• It is not formally documented. However, most of this document does apply to SIP v3.x - just don't be surprised if you come across something that doesn't.

New releases of SIP v3.x may be made in the future, but no significant development will be done.

2.1   Downloading SIP

You can get the latest release of the SIP source code from http://www.riverbankcomputing.co.uk/sip/download.php.

SIP is also included with all of the major Linux distributions. However, it is likely to be a version or two out of date.

You may also find more up to date pre-compiled binaries on SourceForge.

2.2   Configuring SIP

After unpacking the source package (either a .tar.gz or a .zip file depending on your platform) you should then check for any README files that relate to your platform.

Next you need to configure SIP by executing the configure.py script. For example:

python configure.py

This assumes that the 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 full set of command line options is:

-h	Display a help message.
-b dir	The SIP code generator will be installed in the directory dir.
-d dir	The SIP module will be installed in the directory dir.
-k	The SIP module will be built as a static library. This is useful when building the SIP module as a Python builtin
-l lib	Explicitly specify the type of Qt library to use, either qt, qt-mt, qt-mtedu or qte. This is useful if, for example, you have the non-threaded (qt) and threaded (qt-mt) versions of the Qt library installed in the same directory.
-p platform	Explicitly specify the platform/compiler to be used by the build system. If Qt support is enabled then the platform/compiler used to build Qt will be used, otherwise a platform specific default will be used. The -h option will display all the supported platform/compilers and the default.
-u	The SIP module will be built with debugging symbols.
-v dir	By default .sip files will be installed in the directory dir.
-x	Disable the SIP module's support for Qt. Support is automatically disabled if the QTDIR environment variables isn't set.

The configure.py script takes many other options that allows the build system to be finely tuned. These are of the form name=value or name+=value. The -h option will display each supported name, although not all are applicable to all platforms.

The name=value form means that value will replace the existing value of name.

The name+=value form means that value will be appended to the existing value of name.

For example, the following will reduce the size of module binaries compiled with GCC:

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

A pure Python module called sipconfig.py is generated by configure.py. This defines each name and its corresponding value. Looking at it will give you a good idea of how the build system uses the different options.

sipconfig.py is covered in detail in The SIP Build System.

2.3   Building SIP

The next step is to build SIP by running your platform's make command. For example:

make

The final step is to install SIP by running the following command:

make install

(Depending on your system you may require root or administrator privileges.)

This will install the SIP code generator (sip or sip.exe), the SIP module (sip.so or sip.pyd), the SIP build system (sipconfig.py), and a header file (sip.h).