.. _generating-pybind11-bindings:

Generating pybind11 bindings
=====================

SMTK's pybind11_ bindings are generated via python scripts that use
pygccxml_ to construct a C++ header file corresponding to each header
file in SMTK, and a C++ source file for each namespace in
SMTK. Generally, python modules are a reflection of C++ namespaces
(which are generally contained within a subdirectory). The generated
pybind11 C++ files for each module are in the ``pybind`` subdirectory of
the module.

To generate a C++ header file for a new SMTK class, use
``[smtk-root-directory]/utilities/python/cpp_to_pybind11.py`` with the
appropriate arguments for the header file, project root directory,
include directories and generated file prefix; the module's binding
source file (also located in in the ``pybind`` subdirectory of the
module) must then be updated to call the functions defined in the
generated header file. To generate all of the C++ headers and the module C++
source file for a namespace at once, use
``[smtk-root-directory]/utilities/python/generate_pybind11_module.py``
with the appropriate arguments for the module directory, project root
directory and include directories.

The generated bindings should be treated as a starting point for
customization to create a more *pythonic* interface.

.. _pybind11: http://pybind11.readthedocs.io
.. _pygccxml: http://pygccxml.readthedocs.io
