Python bindings

The following is in features/python branch for now

• The bindings are generated by SWIG
• Testing is done by behave

SWIG was chosen because it is a fairly popular wrapper language for C/C++. It less verbose than bare-metal C API, and less painful to install than boost::python. Furthermore, it could be used to generate bindings to other languages as well (R, for instance). The interface files will reside in likelihood/python/. It seems CMake has difficulty generating dependency graphs for this tool, so it might mean we must stick to a single file.

behave provides a Behavior Driven Development interface for python. Since python is likely to provide the glue between mechanisms, likelihood, and optimizers, it makes sense to use this " Given A, When B happens, Then C results " testing framework. Currently, features are located in likelihood/python/features, and feature implementations in likelihood/python/features/steps. It is not yet in the cmake testing framework. It needs to be run from the commandline after installation.

> behave /path/to/dcprogs/likelihood/python/features/ 

Python bindings on Windows

As usual, it is a bit more difficult than strictly necessary. I'm currently working with the anaconda stack. This is a free distribution with any combination of 32bit/64bit python 2.7/python 3.3.

There are also two main compilation environment, which makes things a bit more difficult.

### With Visual Studio:

CMake has to be told explicitly where to find python:

> cmake -DPYTHON_LIBRARY=C:\Anaconda\libs\python27.lib -DPYTHON_INCLUDE_DIR=C:\Anaconda\include -DCMAKE_INSTALL_PREFIX:PATH=$env:HOME\software ..

The last switch above, -DCMAKE_INSTALL_PREFIX:PATH=$env:HOME tells cmake where the code should be installed. It will all go in a "dcprogs" folder within the folder given here. The command-line above works for powershell. cmd.exe users may want to replace $env:HOME with %HOME%.

Warning: The version of anaconda and the compilation target, whether 32bit or 64bit, must match! On my 64bit system, where I have anaconda 64bit, the command becomes:

> cmake -DPYTHON_LIBRARY=C:\Anaconda\libs\python27.lib -DPYTHON_INCLUDE_DIR=C:\Anaconda\include -G  "Visual Studio 11 Win64" ..

Most python distributions will only include a "release" version of the shared libraries, and no "debug" version. Since it is far beyond Microsoft's ken to allow mixing debug and non-debug code, this means the Release configuration is the only one allowed. IDE users should go ahead and click there way to compiling the Release configuration. Command-line users can use the following:

> cd /path/to/build/directory
> cmake --build . --config Release

The best solution is still to switch to a non-proprietary operating system. Barring that, the non-proprietary compiler option is described below.

With MinGW and MSYS:

The command now becomes:

$ cmake -DPYTHON_LIBRARY=C:/Anaconda/libs/libpython27.a -DPYTHON_INCLUDE_DIR=C:/Anaconda/include -DPYTHON_EXECUTABLE=C:/Anaconda/python.exe -DCMAKE_INSTALL_PREFIX=$HOME/software -G "MSYS Makefiles" .. 

Please note that the library against which to link has changed. Generally, python is compiled with Visual Studio. This means that the python dll is incompatible (in some trivially Microsoft TM way) with gcc and gcc code and we have to use this static library instead.

Python Bindings on Mac/Linux

Python bindings should work fairly well on Mac and Linux, with one major caveat. If there are more than one version of python installed on the system, it is very likely that CMake will pick up the wrong one. As such, one should always verify that PYTHON_EXECUTABLE, PYTHON_INCLUDE_DIR, and PYTHON_LIBRARY (in "build/CMakeCache.txt", or via "ccmake") point to the right python and point to the same python. Otherwise, the DCProgs will segfault dramatically when run from python.

Running the tests

The test rely on behave. Unfortunately, there is a bug in the current release version of behave which make it impossible to spew out junit output. Since we use junit in our continuous integration platform, it is necessary to install behave from source:

> git clone https://github.com/behave/behave
> cd behave
> python build install

The above should do the trick.

Once behave has been installed, the test should run through ctest:

> make 
> make test

The test will install dcprogs to a directory in the build tree. This is mainly to have python pickup the dcprogs package that is being compiled. There is yet no automatic installation of behave. And there is something broken with behave's junit interface.

On Windows with Visual Studio, things are more complicated, as always. This time the command is:

> cd /path/to/build
> cmake --build . --config Release
> ctest . -C Release