sipref.txt

这是关于RFC3261实现sip的源代码

=====================================================================
 SIP - A Tool for Generating Python Bindings for C and C++ Libraries
=====================================================================

-----------------
 Reference Guide
-----------------

:Contact:   [e-mail]
:Version:   4.4.3
:Copyright: Copyright (c) 2006 Riverbank Computing Limited

.. contents::
.. section-numbering::


Introduction
============

This is the reference guide for SIP 4.4.3.  SIP is a tool for
automatically generating `Python <http://www.python.org>`__ bindings for C and
C++ libraries.  SIP was originally developed in 1998 for
`PyQt <http://www.riverbankcomputing.co.uk/pyqt/>`__ - the Python bindings for
the Qt GUI toolkit - but is suitable for generating bindings for any C or C++
library.

This version of SIP generates bindings for Python v2.3 or later.  If you want
to generate bindings for earlier versions of Python (going back as far as
Python v1.5) then you need to use `SIP v3.x`_.

There are many other similar tools available.  One of the original such tools
is `SWIG <http://www.swig.org>`__ and, in fact, SIP is so called because it
started out as a small SWIG.  Unlike SWIG, SIP is specifically designed for
bringing together Python and C/C++ and goes to great lengths to make the
integration as tight as possible.

The homepage for SIP is http://www.riverbankcomputing.co.uk/sip/.  Here you
will always find the latest stable version, current development snapshots, and
the latest version of this documentation.


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.


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 global and class operators

    - support for C++ namespaces

    - support for C++ templates

    - 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 global 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

    - support for building your extensions using distutils

    - SIP, and the bindings it produces, runs under UNIX, Linux, Windows and
      MacOS/X


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.


SIP Components
--------------

SIP comprises a number of different components.

    - The SIP code generator (``sip`` or ``sip.exe``).  This processes ``.sip``
      specification files and generates C or C++ bindings.  It is covered in
      detail in `Using SIP`_.

    - The SIP header file (``sip.h``).  This contains definitions and data
      structures needed by the generated C and C++ code.

    - The SIP module (``sip.so`` or ``sip.pyd``).  This is a Python extension
      module that is imported automatically by SIP generated bindings and
      provides them with some common utility functions.  See also `Using the
      SIP Module in Applications`_.

    - The SIP build system (``sipconfig.py``).  This is a pure Python module
      that is created when SIP is configured and encapsulates all the necessary
      information about your system including relevant directory names,
      compiler and linker flags, and version numbers.  It also includes several
      Python classes and functions which help you write configuration scripts
      for your own bindings.  It is covered in detail in `The SIP Build
      System`_.

    - The SIP distutils extension (``sipdistutils.py``).  This is a distutils
      extension that can be used to build your extension modules using
      distutils and is an alternative to writing configuration scripts with the
      SIP build system.  This can be as simple as adding your .sip files to the
      list of files needed to build the extension module.  It is covered in
      detail in `Building Your Extension with distutils`_.


Qt Support
----------

SIP has specific support for the creation of bindings based on Trolltech's Qt
toolkit.

The SIP code generator understands the signal/slot type safe callback mechanism
that Qt uses to connect objects together.  This allows applications to define
new Python signals, and allows any Python callable object to be used as a slot.

SIP itself does not require Qt to be installed.


Potential Incompatibilities with Earlier Versions
=================================================

SIP v4.4
--------

    - The ``SIP_BUILD`` C preprocessor symbol has been removed.

    - `sipConvertToCpp()`_, `sipIsSubClassInstance()`_ and the old `Generated
      Type Convertors`_ have been deprecated.  The functions
      `sipCanConvertToInstance()`_, `sipConvertToInstance()`_,
      `sipForceConvertToInstance()`_, `sipConvertFromInstance()`_,
      `sipConvertFromNewInstance()`_, `sipCanConvertToMappedType()`_,
      `sipConvertToMappedType()`_, `sipForceConvertToMappedType()`_ and
      `sipConvertFromMappedType()`_ should be used instead.  Handwritten
      `%ConvertFromTypeCode`_ and `%ConvertToTypeCode`_ now has the
      responsibility for using these to implement the ``Transfer`` and
      ``TransferBack`` annotations.


Installing SIP
==============

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
may be a version or two out of date.

You may also find more up to date pre-compiled binaries on
`SourceForge <http://sourceforge.net/project/showfiles.php?group_id=61057>`_.


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:\python24\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.

The full set of command line options is:

-h       Display a help message.
-a       Export all symbols in any SIP generated module and the SIP module
         itself.  This was the default behaviour of SIP prior to v4.2.
         Normally only a module's inititialisation function is exported.  This
         option is deprecated as the ``ModuleMakefile`` class of `The SIP Build
         System`_ allows this to be specified on a per module basis.
-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``.
-e dir   The SIP header file 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 (see
         `Builtin Modules and Custom Interpreters`_).
-p plat  Explicitly specify the platform/compiler to be used by the build
         system, 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``.

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 disable support for C++ exceptions (and so
reduce the size of module binaries) when used with GCC::

    python configure.py CXXFLAGS+=-fno-exceptions

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.  It is
covered in detail in `The SIP Build System`_.


Configuring SIP Using MinGW
***************************

SIP, and the modules it generates, can be built with MinGW, the Windows port of
GCC.  You must use the ``-p`` command line option to specify the correct
platform.  For example::

    c:\python24\python configure.py -p win32-g++


Configuring SIP Using the Borland C++ Compiler
**********************************************

SIP, and the modules it generates, can be built with the free Borland C++
compiler.  You must use the ``-p`` command line option to specify the correct
platform.  For example::

    c:\python24\python configure.py -p win32-borland

You must also make sure you have a Borland-compatible version of the Python
library.  If you are using the standard Python distribution (built using the
Microsoft compiler) then you must convert the format of the Python library.
For example::

    coff2omf python24.lib python24_bcpp.lib


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 various SIP components.


Using SIP
=========

Bindings are generated by the SIP code generator from a number of specification
files, typically with a ``.sip`` extension.  Specification files look very
similar to C and C++ header files, but often with additional information (in
the form of a *directive* or an *annotation*) and code so that the bindings
generated can be finely tuned.


A Simple C++ Example
--------------------

We start with a simple example.  Let's say you have a (fictional) C++ library
that implements a single class called ``Word``.  The class has one constructor
that takes a ``\0`` terminated character string as its single argument.  The
class has one method called ``reverse()`` which takes no arguments and returns
a ``\0`` terminated character string.  The interface to the class is defined in
a header file called ``word.h`` which might look something like this::

    // Define the interface to the word library.

    class Word {
        const char *the_word;

    public:
        Word(const char *w);

        char *reverse() const;
    };

The corresponding SIP specification file would then look something like this::