bbmp_interop is an automatic code-generator for pybind11 and a
corresponding CMake module.
It aims to reduce the user written boilerplate to an absolute minimum, when
exporting C++ functions to a Python extension module. If you have a target
foo written in C++, adding the following line to your build will create a
shared library target, i.e. a Python extension module, called pyfoo.
bbmp_add_python_module(pyfoo LINK_LIBRARIES foo)
The module is entirely autogenerated, and will expose any function in foo
that was annotated with the EXPORT_TO_PYTHON definition.
The original library target foo will remain unchanged. It does not need to
depend on Python as pybind11 can convert between many C++ STL and Python
types. Moreover bbmp_interop can convert between Numpy ndarray parameters
and a thin wrapper type that has no dependency on Python.
The pybind11 library is included, so the only dependency you need is Python
3.6.
You can use the library either by installing it and then using
find_package(bbmp_interop 0.1 REQUIRED)
or by placing it into your project and using add_subdirectory.
You will see examples for both usages in tests/test_export_import.py,
although the projects are constructed during runtime in a temporary directory,
so it's easier to begin with the CMake project inside the tests directory.
Adding the package will add the bbmp_types (or bbmp::bbmp_types in case of
installing) target to your project.
Merely by adding the library to your project will not create a dependency on
Python. You can link your libraries against the bbmp_types target if you
wish to use the bbmp::OwnedChannelData<T> type. This type can refer to Numpy
ndarrays, but using them is optional.
Calling bbmp_add_python_module will create three targets: extern_pybind11,
bbmp_python_conversions and the Python extension module, the name of which
is the first argument of bbmp_add_python_module. Generally you shouldn't be
concerned with the first two.
The function calls CMake's FindPython find module internally. Specify
Python_ROOT_DIR or Python_VERSION if you want to influence its result.
The library you want to export functions from need not depend on Python. You
can use standard types that pybind11 understands. In case you want to have a
Numpy ndarray as a parameter, you can use the bbmp::OwnedChannelData<T>
type.
Inside the autogenerated Python module types of bbmp::OwnedChannelData<T>
will be translated to parameters of Numpy ndarray. The
bbmp::OwnedChannelData<T> parameter of your function will have ownership
over the ndarray created in Python, so you can safely keep it even after the
exported function returns.
The CMake project uses CTest. After generating the build you can run ctest --verbose from inside the build directory to run all tests.
I have tested them on Windows 10 (with Visual Studio 2017 and NMake generators) and Ubuntu 20 and GCC.
The extern directory contains code that's part of pybind11.
pybind11 version v2.5.0 from the stable branch. https://github.com/pybind/pybind11 Copyright (c) 2016 Wenzel Jakob [email protected], All rights reserved. Licensed under the 3-clause BSD license.