Automated C++ header wrapping

robotpy-build can be told to parse C/C++ headers and automatically generate pybind11 wrappers around the functions and objects found in that header.

Note

We use a fork of CppHeaderParser to parse headers. We’ve improved it to handle many complicated modern C++ features, but if you run into problems please file a bug on github.

C++ Features

robotpy-build uses a pure python C++ parser and macro processor to attempt to parse header files. As a result, a full AST of the header files is not created. This means particularly opaque code might confuse the parser, as robotpy-build only receives the names, not the actual type information.

However, most basic features typically work without needing to coerce the generator into working correctly, including:

  • functions/methods (overloads, static, etc)

  • public class variables

  • protected class variables are (when possible) exported with a _ prefix

  • inheritance - detects and sets up Python object hierarchy automatically

  • abstract classes - autogenerated code ensures they cannot be created directly

  • virtual functions - automatically generates trampoline classes as described in the pybind11 documentation so that python classes can override them

  • final classes/methods - cannot be overridden from Python code

  • Enumerations

  • Global variables

Additionally, the following features are supported, but require some manual intervention:

To tell the autogenerator to parse headers, you need to add a generate to your package in pyproject.toml:

generate = [
  { demo = "demo.h" }
]

That causes demo.h to be parsed and wrapped.

Note

If you’re importing a large number of headers, the robotpy-build scan-headers tool can generate this for you automatically.

Documentation

robotpy-build will find doxygen documentation comments on many types of elements and use sphinxify to translate them into python docstrings. All elements that support documentation strings can have their docstrings set explicitly using a doc value in the YAML file.

classes:
  X:
    doc: Docstring for this class

Parameters

TODO

Out parameters

TODO

Conditional compilation

Class templates

The code generator needs to be told which instantiations of the class template to create. For a given class:

template <typename T>
struct TBasic
{
    virtual ~TBasic() {}

    T getT() { return t; }
    virtual void setT(const T &t) { this->t = t; }

    T t;
};

You need to tell the code generator two things about your class:

  • Identify the template parameters in the class

  • Declare explicit instantiations that you wish to expose, and their name

To cause a python class to be created called TBasicString which wraps TBasic<std::string>:

classes:
  TBasic:
    template_params:
    - T

templates:
  TBasicString:
    qualname: TBasic
    params:
    - std::string

Function templates

The code generator needs to be told which instantiations of the function template to create. For a given function:

struct TClassWithFn
{
    template <typename T>
    static T getT(T t)
    {
        return t;
    }
};

The following would go in your YAML to create overloads callable from python that call bool getT(bool) and int getT(int).

classes:
  TClassWithFn:
    methods:
      getT:
        template_impls:
        - ["bool"]
        - ["int"]

Differing python and C++ function signatures

Custom configuration of your functions allows you to define a more pythonic API for your C++ classes.

Python only

This often comes up when the python type and a C++ type of a function parameter or return value is different, or you want to omit a parameter. Just define a lambda via cpp_code:

// original code
int foo(int param1);
functions:
  foo:
    cpp_code:
      [](int param1) -> std::string {
        return std::to_string(param1);
      }

If you change the parameters, then you need to use param_override to adjust the parameters. Let’s say you wanted to remove ‘param2’:

functions:
  foo:
    param_override:
      param2:
        ignore: true

Note

When you change things like this, these inline definitions are not callable from C++, you need virtual functions for that.

Python and C++

Let’s say that you have a C++ virtual function void MyClass::foo(std::iostream &s). Semantically, it’s just returning a string. Because you really don’t want to wrap std::iostream, you decide that the function should just return a string in python.

Because this is a virtual function, you need to define a virtual_xform lambda that will take the original arguments, call the python API, then return the original return type. Then when C++ code calls that virtual function, it will call the xform function which will call your python API.

classes:
  MyClass:
    methods:
      foo:
        param_override:
          s:
            ignore: true
        cpp_code: |
          // python API
          [](MyClass * self) -> std::string {
            std::stringstream ss;
            self->foo(ss);
            return ss.str();
          }
        virtual_xform: |
          // C++ virtual function transformer
          [&](py::function &overload) {
            auto s = py::cast<std::string>(overload());
            ss << s;
          }