C++ & sip - 2013

SIP provides C/C++ wrappers to the python code. Python is the driver but C/C++ is not. In other words, SIP just allows us to make C/C++ call from Python but does not make it work calling Python from C/C++. At least, I have not had any luck doing it.

In this tutorial, I'll make a library from C++ code, and use the class and its method from Python side. The example I'll use is the same one given in http://riverbankcomputing.co.uk/static/Docs/sip4/using.html. The C++ code is very simple, and it has a method called reverse() returning a reverse string of a member which was an argument for the constructor of the class.

All of the processes are included in this tutorial: downloading, installing sip, making bindings and using C++ library from Python code.

Among the features of Python that makes it so powerful is it's ability to take existing libraries, written in C/C++, and make them available as Python extension modules. Such extension modules are often called bindings for the library.
SIP is a tool that makes it very easy to create Python bindings for C and C++ libraries. SIP comprises a code generator and a Python module.

1. The code generator
   processes a set of specification files(.sip) and generates C or C++ code which is then compiled to create the bindings extension module.
2. The SIP Python module
   provides support functions to the automatically generated code.

The specification files contains a description of the interface of the C or C++ library, i.e. the classes, methods, functions and variables. The format of a specification file is almost identical to a C or C++ header file. Therefore, the easiest way of creating a specification file is to edit the corresponding header file.

SIP is a tool for quickly writing Python modules that interface with C++ and C libraries.PythonInfo Wiki

SIP is Python extension module generator for C and C++ libraries. It is an extension module generator similar to SWIG but is specifically designed for creating Python modules http://pypi.python.org/pypi/SIP

SIP takes a set of specification (.sip) files describing the API and generates the required C++ code. This is then compiled to produce the Python extension modules. A .sip file is basically the class header file with some things removed (because SIP doesn't include a full C++ parser) and some things added (because C++ doesn't always provide enough information about how the API works). From http://en.wikipedia.org/wiki/SIP_(software)

SIP is a tool that lets you create C and C++ bindings for Python. It was originally created for the PyQt package, which provides Python bindings for Nokia's Qt toolkit. As such, Python-SIP has specific support for the Qt signal/slot mechanism. However, the tool can also be used to create bindings for any C++ API. SIP works in a very similar fashion to SWIG(Simplified Wrapper and Interface Generator), although it does not support the range of languages that SWIG does. SIP supports much of the C/C++ syntax for its interface specification files and uses a similar syntax for its commands as SWIG(i.e., tokens that start with a % symbol), although it supports a different set and style of commands to customize the binding. - From API design for C++ by Martin Reddy.

We can get the latest release of the SIP source code from http://www.riverbankcomputing.com/software/sip/download. In this tutorial, I'm using Ubuntu 11.04.

$ tar xvzf sip-4.13.3.tar.gz

Let's check the files in the directory:

~/Downloads/sip-4.13.3$ ls
configure.py  LICENSE       NEWS             sipgen       specs
custom        LICENSE-GPL2  README           siplib       sphinx
doc           LICENSE-GPL3  sipdistutils.py  siputils.py

If we run the configure.py to configure SIP:

~/Downloads/sip-4.13.3$ python configure.py
This is SIP 4.13.3 for Python 2.7.1+ on linux2.
The SIP code generator will be installed in /usr/bin.
The sip module will be installed in /usr/lib/python2.7/dist-packages.
The sip.h header file will be installed in /usr/include/python2.7.
The default directory to install .sip files in is /usr/share/sip.
The platform/compiler configuration is linux-g++.
Creating siplib/sip.h...purp
Creating siplib/siplib.c...
Creating siplib/siplib.sbf...
Creating sipconfig.py...
Creating top level Makefile...
Creating sip code generator Makefile...
Creating sip module Makefile...

Then, we have the following files in the same directory:

~/Downloads/sip-4.13.3$ ls
configure.py  LICENSE-GPL2  README           sipgen        specs
custom        LICENSE-GPL3  sipconfig.py     siplib        sphinx
doc           Makefile      sipconfig.pyc    siputils.py
LICENSE       NEWS          sipdistutils.py  siputils.pyc

The configure.py generated a Makefile for us:

# Makefile
all:
        @(cd sipgen; $(MAKE))
        @(cd siplib; $(MAKE))

install:
        @(cd sipgen; $(MAKE) install)
        @(cd siplib; $(MAKE) install)
        @test -d $(DESTDIR)/usr/lib/python2.7/dist-packages || mkdir -p $(DESTDIR)/usr/lib/python2.7/dist-packages
        cp -f sipconfig.py $(DESTDIR)/usr/lib/python2.7/dist-packages/sipconfig.py
        cp -f /home/kihyuck/Downloads/sip-4.13.3/sipdistutils.py $(DESTDIR)/usr/lib/python2.7/dist-packages/sipdistutils.py

clean:
        @(cd sipgen; $(MAKE) clean)
        @(cd siplib; $(MAKE) clean)

So, if we do make:

~/Downloads/sip-4.13.3$ make
gcc -c -pipe -O2 -w -DNDEBUG -I. -o main.o main.c
gcc -c -pipe -O2 -w -DNDEBUG -I. -o transform.o transform.c
gcc -c -pipe -O2 -w -DNDEBUG -I. -o gencode.o gencode.c
gcc -c -pipe -O2 -w -DNDEBUG -I. -o extracts.o extracts.c
gcc -c -pipe -O2 -w -DNDEBUG -I. -o export.o export.c
gcc -c -pipe -O2 -w -DNDEBUG -I. -o heap.o heap.c
gcc -c -pipe -O2 -w -DNDEBUG -I. -o parser.o parser.c
gcc -c -pipe -O2 -w -DNDEBUG -I. -o lexer.o lexer.c
g++  -o sip main.o transform.o gencode.o extracts.o export.o heap.o parser.o lexer.o 
...
gcc -c -pipe -fPIC -O2 -w -DNDEBUG -I. -I/usr/include/python2.7 -o siplib.o siplib.c
gcc -c -pipe -fPIC -O2 -w -DNDEBUG -I. -I/usr/include/python2.7 -o apiversions.o apiversions.c
gcc -c -pipe -fPIC -O2 -w -DNDEBUG -I. -I/usr/include/python2.7 -o descriptors.o descriptors.c
gcc -c -pipe -fPIC -O2 -w -DNDEBUG -I. -I/usr/include/python2.7 -o qtlib.o qtlib.c
gcc -c -pipe -fPIC -O2 -w -DNDEBUG -I. -I/usr/include/python2.7 -o threads.o threads.c
gcc -c -pipe -fPIC -O2 -w -DNDEBUG -I. -I/usr/include/python2.7 -o objmap.o objmap.c
gcc -c -pipe -fPIC -O2 -w -DNDEBUG -I. -I/usr/include/python2.7 -o voidptr.o voidptr.c
g++ -c -pipe -fPIC -O2 -w -DNDEBUG -I. -I/usr/include/python2.7 -o bool.o bool.cpp
g++ -shared -Wl,--version-script=sip.exp -o sip.so siplib.o apiversions.o descriptors.o qtlib.o threads.o objmap.o voidptr.o bool.o 
...

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

~/Downloads/sip-4.13.3$ sudo make install 
make[1]: Entering directory `/home/kihyuck/Downloads/sip-4.13.3/sipgen'
cp -f sip /usr/bin/sip
make[1]: Leaving directory `/home/kihyuck/Downloads/sip-4.13.3/sipgen'
make[1]: Entering directory `/home/kihyuck/Downloads/sip-4.13.3/siplib'
cp -f sip.so /usr/lib/python2.7/dist-packages/sip.so
strip /usr/lib/python2.7/dist-packages/sip.so
cp -f /home/kihyuck/Downloads/sip-4.13.3/siplib/sip.h /usr/include/python2.7/sip.h
make[1]: Leaving directory `/home/kihyuck/Downloads/sip-4.13.3/siplib'
cp -f sipconfig.py /usr/lib/python2.7/dist-packages/sipconfig.py
cp -f /home/kihyuck/Downloads/sip-4.13.3/sipdistutils.py /usr/lib/python2.7/dist-packages/sipdistutils.py

Let's make a new directory, MySip, and with a specification file, word.sip.

~/MySip$ ls
word.sip

and the word.sip should look like below and it is very similar to word.h:

// word.sip
// Define the SIP wrapper to the word library.

%Module word

class Word {

%TypeHeaderCode
#include <word.h>
%End

public:
    Word(const char *w);
purp
    char *reverse() const;
};

Let's compare it with word.h below:

// Define the interface to the word library.

class Word {
    const char *the_word;

public:
    Word(const char *w);

    char *reverse() const;
};

If we want, we can now generate the C++ code in the current directory:

~/MySip$ sip -c . word.sip
~/MySip$ ls
sipAPIword.h  sipwordcmodule.cpp  sipwordWord.cpp  word.sip

It created the following:

1. sipAPI$(module).h, sip$(module)$(class).cpp
   A pair of corresponding header and C++ files for each wrapped class.
2. $(module)cmodule.cpp
   Which contains the module global and initialization code.

However, we want to use script, configure.py, for the tasks such as compiling the generated code and linking it against all the necessary libraries

~/MySip$ ls
configure.py  word.sip

The configure.py looks like this:

# configure.py
######################
import os
import sipconfig

# The name of the SIP build file generated by SIP and used by the build
# system.
build_file = "word.sbf"

# Get the SIP configuration information.
config = sipconfig.Configuration()

# Run SIP to generate the code.
os.system(" ".join([config.sip_bin, "-c", ".", "-b", build_file, "word.sip"]))

# Create the Makefile.
makefile = sipconfig.SIPModuleMakefile(config, build_file)

# Add the library we are wrapping.  The name doesn't include any platform
# specific prefixes or extensions (e.g. the "lib" prefix on UNIX, or the
# ".dll" extension on Windows).
makefile.extra_libs = ["word"]

# Generate the Makefile itself.
makefile.generate()
#####################

Then, we can run the script configure.py, and see what's been changed:

~/MySip$ python configure.py

~/MySip$ ls
configure.py  Makefile  sipAPIword.h  sipwordcmodule.cpp  sipwordWord.cpp  word.sbf  word.sip

If we run make, we get the following error:

~/MySip$ make
g++ -c -pipe -fPIC -O2 -Wall -W -DNDEBUG -I. -I/usr/include/python2.7 -o sipwordWord.o sipwordWord.cpp
word.sip:8:18: fatal error: word.h: No such file or directory
compilation terminated.
make: *** [sipwordWord.o] Error 1

So, we need to put word.h at standard location for compiler such as /usr/include/. After doing it, if we run make, we get the following:

~/MySip$ make
g++ -c -pipe -fPIC -O2 -Wall -W -DNDEBUG -I. -I/usr/include/python2.7 -o sipwordWord.o sipwordWord.cpp
g++ -shared -Wl,--version-script=word.exp -o word.so sipwordcmodule.o sipwordWord.o -lword
/usr/bin/ld: cannot find -lword
collect2: ld returned 1 exit status
make: *** [word.so] Error 1

That's because we do not have a wordlib.a in the standard search location for compiler. The sip documents from http://www.riverbankcomputing.co.uk/static/Docs/sip4/using.html assumed that the word library we are wrapping and it's header file are installed in standard system locations and will be found by the compiler and linker without having to specify any additional flags. But I'll put the word.h into /usr/include/ and libword.a into /usr/lib.

So, we need to make the wordlib.a, and here is the code:

// word.cpp

#include <string.h>
#include <iostream>
#include <word.h>

using namespace std;

Word::Word(const char *w)
{
        the_word = w;
}

char* Word::reverse() const
{
        int len = strlen(the_word);
        char *str = new char[len+1];
        for(int i = len-1;i >= 0 ;i--) {
                str[len-1-i] = the_word[i];
        }
        str[len+1]='\0';
        return str;
}

and then, made the lib:

~/TEST/$ g++ -c word.cpp
~/TEST/$ ar -crs libword.a word.o
~/TEST/$ sudo cp libword.a /usr/lib

Then, we need to make and make install:
run the make again:

~/MySip$ make
g++ -c -pipe -fPIC -O2 -Wall -W -DNDEBUG -I. -I/usr/include/python2.7 -o sipwordcmodule.o sipwordcmodule.cpp
g++ -c -pipe -fPIC -O2 -Wall -W -DNDEBUG -I. -I/usr/include/python2.7 -o sipwordWord.o sipwordWord.cpp
g++ -shared -Wl,--version-script=word.exp -o word.so sipwordcmodule.o sipwordWord.o -lword

~/MySip$ ls
configure.py  sipAPIword.h        sipwordcmodule.o  sipwordWord.o  word.sbf  word.so
Makefile      sipwordcmodule.cpp  sipwordWord.cpp   word.exp       word.sip

and then install:

~/MySip$ sudo make install
cp -f word.so /usr/lib/python2.7/dist-packages/word.so
strip /usr/lib/python2.7/dist-packages/word.so

Now we can access to the C++ library from Python.

Here is a very simple Python file to run:

from word import Word

w = Word("reverse me")
print  w.reverse()

If we run it:

em esrever