In this section we describe basic Binder usage.
In order to create shared library that will provide bindings to C++ code we need to:
- Gather data about what classes/functions are available and acquire in-depth information of class heritage, member functions and standalone functions type signatures.
- Generate bindings code
- 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>
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.
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