C++ binding generator for CPython 3.x (x>=2), Lua 5.3 and Go
Fabgen is a set of Python scripts to generate C++ binding code to different languages.
It was written as a SWIG replacement for the Harfang Multimedia Framework (http://www.harfang3d.com).
Fabgen is written and maintained by Emmanuel Julien for the Harfang Multimedia Framework (http://www.harfang3d.com).
Fabgen GO is written and maintained by Thomas Simonnet for the Harfang Multimedia Framework (http://www.harfang3d.com).
Fabgen is licensed under the GPLv3.
Fabgen output does not fall under the GPLv3, you are free to license it as you please.
arg_out
, arg_in_out
to support output arguments.route
to route methods to a customizable expression.proxy
to support wrapper types such as std::shared_ptr<T>.Py_Limited_API
) (generated modules can be used on all CPython version >=3.2)Contributions are welcome. Please submit merge requests with working unit test to the project Github directly.
Generate binding for CPython 3
bind.py api_binding_script.py --cpython --out d:\
Generate binding for Lua 5.3
bind.py api_binding_script.py --lua --out d:\
Generate binding for GO
Installation:
go get golang.org/x/tools/cmd/goimports
bind.py api_binding_script.py --go --out d:\
Refer to the provided example and the tests for how to write your own API binding script.
Type converters and function prototypes all accept a list or dictionary of features when declared.
Types using this feature are declared as wrapper for another underlying type.
This feature is used to unwrap arguments to a call and wrap its return value.
Note: A type converter proxy feature is consumed by prototypes proxy feature, see the prototype feature documentation.
Support for std::shared_ptr is done with the proxy feature.
def transform(gen, conv, expr, var_out, ownership):
Allow type conversion when returned from a function.
class StdSharedPtrProxyFeature:
def __init__(self, wrapped_conv):
self.wrapped_conv = wrapped_conv
def init_type_converter(self, gen, conv):
# declare shared_ptr<T> to T cast support
gen.add_cast(conv, self.wrapped_conv, lambda in_var, out_var: '%s = ((%s *)%s)->get();\n' % (out_var, conv.ctype, in_var))
def unwrap(self, in_var, out_var):
return '%s = %s->get();\n' % (out_var, in_var)
def wrap(self, in_var, out_var):
return '%s = new std::shared_ptr<%s>(%s);\n' % (out_var, self.wrapped_conv.ctype, in_var)
Provide native access for the target language to values stored in a container type.
Provide a custom representation for a type.
def get_repr(var_self, var_repr):
return '%s = "custom_repr";\n' % var_repr # C++ code to evaluate at runtime and assign to the repr string
This feature redirects an object method (static or not) to a function with a compatible signature. It can be used to extend classes with additional methods while not modifying the existing C++ class.
Dictionary of argument names to consider as output to the bound function. Output arguments do not take part in overload resolution and are not provided by the function caller.
Output arguments are appended to the function return value.
Dictionary of argument names to consider as input-output to the bound function. Input-output arguments take part in overload resolution and are provided by the function caller.
Input-output arguments are appended to the function return value.
Route a method call to the type wrapped by the 'proxy' feature of the converter used of the declaration. This feature does not provide any value. This feature can be used to wrap constructors.
# With shared_ptr_to_obj_conv being a TypeConverter with a proxy feature,
# call the PrintState method through the shared pointer.
gen.bind_method(shared_ptr_to_obj_conv, 'PrintState', 'void', [], features=['proxy'])
By default, values returned by reference or pointer are assumed C++ ownership. This feature transfers the returned object ownership to the target language.
By default, values returned by reference or pointer are assumed C++ ownership. This feature makes a copy of the returned object, the target language then has full ownership.
Insert return value checking code right after the native call.
Wrap the native function call with a try{} block and raises an exception in the target language with the specified string as the exception message.
Consider the following example scenario when binding std::vector<int>
to CPython:
std::vector<int>
, the other one a PySequence of int as a convenience to the user.std::vector<int>
as PySequence during dynamic dispatch since it implements the Sequence protocol.This can have serious performance implications as the PySequence always need to be extracted to a temporary std::vector<int>
before the native call is made.
A wrapped std::vector<int>
object does not undergo any transformation and is passed right away to the native layer.