The Basics

In this section we describe basic Binder usage.

Principles

In order to create shared library that will provide bindings to C++ code we need to:

  1. Gather data about what classes/functions are available and acquire in-depth information of class heritage, member functions and standalone functions type signatures.
  2. Generate bindings code
  3. Compile code into shared library

Binder is tool that aims to automate steps 1 and 2.

Preparing the input file

In order to feed Binder information about our underlying C++ code we need to create special C++ include file that in turn includes all header files from our project. For example: suppose that our C++ project contain the following header files: frutes/apple.hpp, frutes/orange.hpp and vegetables/tomato.hpp. In this case our special include file should contain something like this:

#include <frutes/apple.hpp>
#include <frutes/orange.hpp>
#include <vegetables/tomato.hpp>

Note

Make sure to specify complete-relative-to-project-root path to includes and use #include <file> and avoid using #include "file" form. That way Binder will be able to determine correct include paths for each include which is essential for generating correct include sets on step 2. To bulk-convert quote-includes to angle-bracker-include please see https://github.com/shakfu/header_utils project.

For small projects such file could be simply typed by-hands and for large project it might be more practical to use a scripts to do so.

Running the Binder

After the input file is ready the next step is to run Binder. Assuming that our include file containing all headers from the project is named as all_includes.hpp it could be done as:

binder --root-module my_project --prefix $HOME/my_project/bindings/source \
  --bind my_root_namespace \
  all_includes.hpp \
  -- -std=c++11 -I$HOME/my_project/include -I$HOME/extra/some_libs \
  -DMY_PROJECT_DEFINE -DNDEBUG

Note that we have to specify project-wide include path so Binder could find includes specifies in all_includes.hpp as well as path to any additional C++ include headers that is used in project.

Most big project will probably require fine tunning of bindings generation process. This can be done by creating Binder config file and specifying it when calling Binder as --config my_project.config. For detailed reference of config file options please see Configuration.

Compiling generated code

If all goes well and Binder finished its run without error the path specified by --prefix option should contain generated source code and auxiliary files:

<root_module_name>.sources list of generated source files

<root_module_name>.cpp main file for binding code

<root_module_name>.modules file containing the list of Python modules that were generated