使用Shiboken为C++和Qt库创建Python绑定

Shiboken的资料真少，仅仅为了写一个小小的demo就大费周折。但不管怎样，经过几个月断断续续的了解，总算可以为纯C++的库和Qt的库创建python的绑定了。
本文前提：
熟悉cmake，能够用cmake构建C++与Qt的程序和库

安装有Python和Shiboken的开发环境

安装有PySide和Qt4(4.6及以上)的开发环境

注意：若在windows下，Shiboken和PySide开发环境需要自己编译

接下来记录两个例子：(本文例子仅在Windows和Ubuntu环境下进行过测试)

创建C++库的绑定

步骤：
创建一个普通的 C++ 的库 foo.dll 或 libfoo.so

使用shiboken生成胶水代码

编译胶水代码生成绑定库 foo.pyd 或 foo.so

编写python程序进行测试

看一下本例用到的所有文件：

|-- CMakeLists.txt
|
|-- libfoo/
|      |-- CMakeLists.txt
|      |-- foo.h
|      `-- foo.cpp
|
|-- foobinding/
|      |-- CMakeLists.txt
|      |-- foo/
|      |      |-- CMakeLists.txt
|      |      |-- global.h
|      |      `-- typesystem_foo.xml
|      `-- tests/
|             |-- CMakeLists.txt
|             `-- test_foo.py

顶层的CMakeLists.txt 文件内容如下：

cmake_minimum_required(VERSION 2.8)
add_subdirectory(libfoo)
add_subdirectory(foobinding)
enable_testing()

libfoo

libfoo 中是我们原始的需要绑定的C++代码，可以快速一下这3个文件
CMakeLists.txt

project(libfoo)
set(LIB_SRC foo.cpp)
add_definitions("-DLIBFOO_BUILD")
add_library(libfoo SHARED ${LIB_SRC})
set_target_properties(libfoo PROPERTIES OUTPUT_NAME "foo")

foo.h

#ifndef FOO_H
#define FOO_H

#if defined _WIN32
#if LIBFOO_BUILD
#define LIBFOO_API __declspec(dllexport)
#else
#define LIBFOO_API __declspec(dllimport)
#endif
#else
#define LIBFOO_API
#endif

class LIBFOO_API Math
{
public:
Math(){}
~Math(){}
int squared(int x);
};
#endif // FOO_H

foo.cpp

#include "foo.h"

int Math::squared(int x)
{
return x * x;
}

这部分没有什么特别的东西，直接看绑定部分

foobinding

CMakeLists.txt 文件内容

project(foobinding)

cmake_minimum_required(VERSION 2.6)

find_package(PythonLibs REQUIRED)
find_package(Shiboken REQUIRED)

find_program(GENERATOR generatorrunner REQUIRED)
if (NOT GENERATOR)
message(FATAL_ERROR "You need to specify GENERATOR variable (-DGENERATOR=value)")
endif()

if(CMAKE_HOST_UNIX)
option(ENABLE_GCC_OPTIMIZATION "Enable specific GCC flags to optimization library size and performance. Only available on Release Mode" 0)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -fvisibility=hidden -Wno-strict-aliasing")
set(CMAKE_CXX_FLAGS_DEBUG "-g")
if(ENABLE_GCC_OPTIMIZATION)
set(CMAKE_BUILD_TYPE Release)
set(CMAKE_CXX_FLAGS_RELEASE "-DNDEBUG -Os -Wl,-O1")
if(NOT CMAKE_HOST_APPLE)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wl,--hash-style=gnu")
endif()
endif()
endif()

enable_testing()

add_subdirectory(foo)
add_subdirectory(tests)

内容本身是简单的，就是
查找python和shiboken的开发包

查找可执行程序generatorrunner

加入两个子目录

只是中间加入的那堆优化选项是文件看起来很乱

foo

这才是我们最重要的部分，先看CMakeLists.txt文件：

project(foo)

set(foo_SRC
${CMAKE_CURRENT_BINARY_DIR}/foo/foo_module_wrapper.cpp
${CMAKE_CURRENT_BINARY_DIR}/foo/math_wrapper.cpp
)

set(foo_INCLUDE_DIRECTORIES
${SHIBOKEN_INCLUDE_DIR}
${PYTHON_INCLUDE_PATH}
${libfoo_SOURCE_DIR}
)

set(foo_LINK_LIBRARIES
${SHIBOKEN_PYTHON_LIBRARIES}
${SHIBOKEN_LIBRARY}
libfoo
)

include_directories(foo ${foo_INCLUDE_DIRECTORIES})
add_library(foo MODULE ${foo_SRC})
set_property(TARGET foo PROPERTY PREFIX "")
if(WIN32)
set_property(TARGET foo PROPERTY SUFFIX ".pyd")
endif()
target_link_libraries(foo ${foo_LINK_LIBRARIES})
add_custom_command(OUTPUT ${foo_SRC}
COMMAND ${GENERATOR}
--generatorSet=shiboken
${CMAKE_CURRENT_SOURCE_DIR}/global.h
--include-paths=${libfoo_SOURCE_DIR}
--output-directory=${CMAKE_CURRENT_BINARY_DIR}
${CMAKE_CURRENT_SOURCE_DIR}/typesystem_foo.xml
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
COMMENT "Running generator for libfoo..."
)

难点就是生成胶水代码（这儿的custom命令）：
它需要一个输入的 global.h 文件和 typesystem_foo.xml 文件

通过 --include-paths 指定global.h中包含的头文件所在的路径

看一下这两个简单的文件：
global.h

#include "foo.h"

typesystem_foo.xml

<?xml version="1.0"?>
<typesystem package="foo">
<primitive-type name="int"/>
<value-type name='Math'/>
</typesystem>

tests

生成东西能否工作呢？需要测试来说话：
CMakeLists.txt

if(WIN32)
set(TEST_PYTHONPATH     "${foo_BINARY_DIR}")
set(TEST_LIBRARY_PATH   "${libfoo_BINARY_DIR};$ENV{PATH}")
set(LIBRARY_PATH_VAR    "PATH")
string(REPLACE "//" "/" TEST_PYTHONPATH "${TEST_PYTHONPATH}")
string(REPLACE "//" "/" TEST_LIBRARY_PATH "${TEST_LIBRARY_PATH}")

string(REPLACE ";" "//;" TEST_PYTHONPATH "${TEST_PYTHONPATH}")
string(REPLACE ";" "//;" TEST_LIBRARY_PATH "${TEST_LIBRARY_PATH}")
else()
set(TEST_PYTHONPATH     "${foo_BINARY_DIR}")
set(TEST_LIBRARY_PATH   "${libfoo_BINARY_DIR}:$ENV{LD_LIBRARY_PATH}")
set(LIBRARY_PATH_VAR    "LD_LIBRARY_PATH")
endif()
add_test(math ${SHIBOKEN_PYTHON_INTERPRETER} ${CMAKE_CURRENT_SOURCE_DIR}/test_foo.py)
set_tests_properties(math PROPERTIES ENVIRONMENT "PYTHONPATH=${TEST_PYTHONPATH};${LIBRARY_PATH_VAR}=${TEST_LIBRARY_PATH}")

呵呵，这个文件看起来真烦！！

概念上还算简单的东西：
调用python来执行我们的测试程序

告诉python我们的绑定在那么路径下（通过环境变量PYTHONPATH）

告诉python去哪儿找需要的动态库（环境变量Unix下LD_LIBRARY_PATH，win下PATH）

windows下需要对路径分隔符进行调整(烦)

至于我们的测试程序，test_foo.py:

# -*- coding: utf-8 -*-

import unittest
import foo

class MathTest(unittest.TestCase):
def testMath(self):
'''Test case for Math class from foo module.'''
val = 5
math = foo.Math()
self.assertEqual(math.squared(5), 5 * 5)

if __name__ == '__main__':
unittest.main()

至此，所有代码看完了。环境准备好，编译就比较简单了，无非
mkdir build

cd build

cmake ..

make

make test

创建自定义Qt库的绑定

操作步骤和文件位置与前面非Qt的情况完全相同：
创建一个普通的 Qt 动态库 foo.dll 或 libfoo.so

使用shiboken生成胶水代码(需要PySide)

编译胶水代码生成绑定库 foo.pyd 或 foo.so

编写python程序进行测试

顶层CMakeLists文件和前面完全相同（此处略）。

libfoo

libfoo 中是我们原始的需要绑定的Qt 代码，可以快速一下这3个文件(与前面相比，就是多了点Qt的元素)
CMakeLists.txt

project(libfoo)
find_package(Qt4 COMPONENTS QtCore REQUIRED)
include(${QT_USE_FILE})
include_directories(${CMAKE_CURRENT_BINARY_DIR})
set(LIB_SRC foo.cpp)
qt4_automoc(${LIB_SRC})
add_definitions("-DLIBFOO_BUILD")
add_library(libfoo SHARED ${LIB_SRC})
target_link_libraries(libfoo ${QT_LIBRARIES})
set_target_properties(libfoo PROPERTIES OUTPUT_NAME "foo")

此处使用的是qt4_automoc方式，你也可以用qt4_wrap_cpp方式(不做解释)
foo.h

#ifndef FOO_H
#define FOO_H
#include <QtCore/QObject>

#if LIBFOO_BUILD
#define LIBFOO_API Q_DECL_EXPORT
#else
#define LIBFOO_API Q_DECL_IMPORT
#endif

class LIBFOO_API Math : public QObject
{
Q_OBJECT
public:
Math();
~Math();
int squared(int x);
};
#endif // FOO_H

派生自QObject，代码整体上比前面的短，因为Q_DECL_EXPORT可以使我们避免自己根据不同平台去定义宏。
foo.cpp

#include "foo.h"

Math::Math()
:QObject(NULL)
{
}

Math::~Math()
{
}

int Math::squared(int x)
{
return x * x;
}

#include "foo.moc"

注意，最后的include语句是配合cmake的qt4_automoc工作的，如果你有在qmake下使用它的经验，请注意它们截然不同。
接下来看绑定部分

foobinding

CMakeLists.txt 文件内容

project(foobinding)

cmake_minimum_required(VERSION 2.6)

find_package(PythonLibs REQUIRED)
find_package(Shiboken REQUIRED)
find_package(PySide REQUIRED)
find_package(Qt4 REQUIRED)

include(${QT_USE_FILE})

find_program(GENERATOR generatorrunner REQUIRED)
if (NOT GENERATOR)
message(FATAL_ERROR "You need to specify GENERATOR variable (-DGENERATOR=value)")
endif()

if(MSVC)
set(CMAKE_CXX_FLAGS "/Zc:wchar_t- /GR /EHsc /DNOCOLOR /DWIN32 /D_WINDOWS /D_SCL_SECURE_NO_WARNINGS")
else()
if(CMAKE_HOST_UNIX)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -fvisibility=hidden -Wno-strict-aliasing")
endif()
set(CMAKE_CXX_FLAGS_DEBUG "-g")
option(ENABLE_GCC_OPTIMIZATION "Enable specific GCC flags to optimization library size and performance. Only available on Release Mode" 0)
if(ENABLE_GCC_OPTIMIZATION)
set(CMAKE_BUILD_TYPE Release)
set(CMAKE_CXX_FLAGS_RELEASE "-DNDEBUG -Os -Wl,-O1")
if(NOT CMAKE_HOST_APPLE)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wl,--hash-style=gnu")
endif()
endif()

if(CMAKE_HOST_APPLE)
if (NOT QT_INCLUDE_DIR)
set(QT_INCLUDE_DIR "/Library/Frameworks")
endif()
if(ALTERNATIVE_QT_INCLUDE_DIR)
set(QT_INCLUDE_DIR ${ALTERNATIVE_QT_INCLUDE_DIR})
endif()
string(REPLACE " " ":" QT_INCLUDE_DIR ${QT_INCLUDE_DIR})
endif()
endif()

set(GENERATOR_EXTRA_FLAGS --generator-set=shiboken --enable-parent-ctor-heuristic --enable-pyside-extensions --enable-return-value-heuristic --use-isnull-as-nb_nonzero)
if(WIN32 OR DEFINED AVOID_PROTECTED_HACK)
message(STATUS "PySide will be generated avoiding the protected hack!")
set(GENERATOR_EXTRA_FLAGS ${GENERATOR_EXTRA_FLAGS} --avoid-protected-hack)
add_definitions(-DAVOID_PROTECTED_HACK)
else()
message(STATUS "PySide will be generated using the protected hack!")
endif()

if (WIN32)
set(PATH_SEP "/;")
else()
set(PATH_SEP ":")
endif()

enable_testing()

add_subdirectory(foo)
add_subdirectory(tests)

和它的前任比较，它复杂很多

除了查找python和shiboken的开发包，它还需要PySide开发环境

除了查找可执行程序generatorrunner，还需要注意它的选项(对Win下，必须 --avoid-protected-hack)

因为要用到多路径，注意不同平台的路径分割符！

foo

同前面一样，此处是生成绑定的地方，也是我们最重要的部分，先看CMakeLists.txt文件：

project(foo)

set(foo_SRC
${CMAKE_CURRENT_BINARY_DIR}/foo/foo_module_wrapper.cpp
${CMAKE_CURRENT_BINARY_DIR}/foo/math_wrapper.cpp
)

set(foo_INCLUDE_DIRECTORIES
${SHIBOKEN_INCLUDE_DIR}
${SHIBOKEN_PYTHON_INCLUDE_DIR}
${PYSIDE_INCLUDE_DIR}
${PYSIDE_INCLUDE_DIR}/QtCore
${libfoo_SOURCE_DIR}
)

set(foo_LINK_LIBRARIES
${SHIBOKEN_PYTHON_LIBRARIES}
${SHIBOKEN_LIBRARY}
${PYSIDE_LIBRARY}
${QT_LIBRARIES}
libfoo
)

include_directories(foo ${foo_INCLUDE_DIRECTORIES})
add_library(foo MODULE ${foo_SRC})
set_property(TARGET foo PROPERTY PREFIX "")
if(WIN32)
set_property(TARGET foo PROPERTY SUFFIX ".pyd")
endif()
target_link_libraries(foo ${foo_LINK_LIBRARIES})

add_custom_command(OUTPUT ${foo_SRC}
COMMAND ${GENERATOR}
--generatorSet=shiboken ${GENERATOR_EXTRA_FLAGS}
${CMAKE_CURRENT_SOURCE_DIR}/global.h
--include-paths=${libfoo_SOURCE_DIR}${PATH_SEP}${QT_INCLUDE_DIR}${PATH_SEP}${PYSIDE_INCLUDE_DIR}
--output-directory=${CMAKE_CURRENT_BINARY_DIR}
--typesystem-paths=${typesystem_path}${PATH_SEP}${PYSIDE_TYPESYSTEMS}
${CMAKE_CURRENT_SOURCE_DIR}/typesystem_foo.xml
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
COMMENT "Running generator for libfoo..."
)

注意和它前任比较，变复杂的部分：

头文件路径，需要Qt的头文件路径和PySide的头文件路径(注意子路径)

链接库，需要Qt的库和PySide的库

generatorrunner 参数中的 --include-paths，添加Qt和PySide路径

generatorrunner 参数中 --typesystem-paths 添加相应路径

看一下另外两个文件：
global.h

#undef QT_NO_STL
#undef QT_NO_STL_WCHAR

#ifndef NULL
#define NULL    0
#endif

#include "pyside_global.h"

#include "foo.h"

几个宏看不太懂，多了一个pyside_global.h文件，属于PySide自带的文件
typesystem_foo.xml

<?xml version="1.0"?>
<typesystem package="foo">
<load-typesystem name="typesystem_core.xml" generate="no"/>
<object-type name='Math' />
</typesystem>

需要加载PySide 的 typesystem_core.xml

tests

生成东西能否工作，仍然需要测试来说话：
CMakeLists.txt

if(WIN32)
set(TEST_PYTHONPATH     "${foo_BINARY_DIR};${PYSIDE_PYTHONPATH}")
set(TEST_LIBRARY_PATH   "${libfoo_BINARY_DIR};$ENV{PATH}")
set(LIBRARY_PATH_VAR    "PATH")
string(REPLACE "//" "/" TEST_PYTHONPATH "${TEST_PYTHONPATH}")
string(REPLACE "//" "/" TEST_LIBRARY_PATH "${TEST_LIBRARY_PATH}")

string(REPLACE ";" "//;" TEST_PYTHONPATH "${TEST_PYTHONPATH}")
string(REPLACE ";" "//;" TEST_LIBRARY_PATH "${TEST_LIBRARY_PATH}")
else()
set(TEST_PYTHONPATH     "${foo_BINARY_DIR}:${PYSIDE_PYTHONPATH}")
set(TEST_LIBRARY_PATH   "${libfoo_BINARY_DIR}:$ENV{LD_LIBRARY_PATH}")
set(LIBRARY_PATH_VAR    "LD_LIBRARY_PATH")
endif()
add_test(math ${SHIBOKEN_PYTHON_INTERPRETER} ${CMAKE_CURRENT_SOURCE_DIR}/test_foo.py)
set_tests_properties(math PROPERTIES ENVIRONMENT "PYTHONPATH=${TEST_PYTHONPATH};${LIBRARY_PATH_VAR}=${TEST_LIBRARY_PATH}")

恩，基本没变化，就是多了个PYSIDE_PYTHONPATH
至于 test_foo.py 文件，和第一部分完全一样，此处略。