Commit 240cf051 authored by Joe Snyder's avatar Joe Snyder
Browse files

Add paragraphs to README about existing tools

parent 30caf5e1
......@@ -230,6 +230,94 @@ or setup a CMake build system and execute the ``WG_Linter`` test::
$ ctest -R WG_Linter -VV
Previous Work:
------------------
Alternatives Comparison
CLIF
####
https://github.com/google/clif
Philosophically in some ways similar to the hooking up CastXML and some code
generator and runtime library (e.g., Pybind11), which would mean most of the
glue that would need to be written is already there. However, it is an
incomplete and apparently dead project (from a public point of view). Also,
no Numpy and Eigen support. It had a high profile developer in Google and there
were once some mentions of CLIF in the Bazel codebase.
Pybind11
########
Definitions are written in C++ code, which is also more familiar to developers
than some intermediate language (like SWIG). Pybind11 (but not Boost Python)
includes extensive Numpy and Eigen support that would take some time to
reimplement. Some features are missing and have been added via patches with
varying success (codebase is difficult to understand). Pybind11 upstream is
generally not responsive to patches (though obviously better than CLIF),
whether Boost Python would be more responsive is unknown.
Several open source projects are already working on generating Pybind11
bindings.
SWIG
####
http://www.swig.org/
Multi-language support would be an advantage. Projects in the open source
community already have code that generates SWIG bindings,
but the authors have stated that if they were starting now, they would use
Pybind11. The SWIG intermediate language is less familiar to Drake developers
than pure C++ and most Numpy and Eigen support would need to be written).
Upstream seems to be responsive, but potentially patches would need
to work for multiple languages that SWIG supports.
CPPWG
#####
https://github.com/jmsgrogan/cppwg/
CPPWG was the first tool used in the attempt to wrap Drake code. This tool
was the inspiration for the structure of the AutoPyBind11 system. It uses
CastXML with pygccxml and nested configuration files to denote what classes and
free functions needed to be wrapped by the tool. It also had a configurable set
of PyBind11 output, but with much less customization opportunity as the
customization was limited to a few specific places in the code as opposed to
the structure of the PyBind11 code which AutoPyBind11 allows.
The tool’s major shortcoming was the method’s handling of templated classes.
It used string matching while parsing the C++ source file to determine if
any of the lines found in the object required templating. Additionally,
a test case was created which found an issue with the usage of templates
of wrapped code using a single instantiation type.
Binder
######
https://github.com/RosettaCommons/binder and https://cppbinder.readthedocs.io/en/latest/
Binder is another tool that performs the automatic wrapping of C++ code into
Python via PyBind11. It uses C++ as the language of the tool, as opposed to
AutoPyBind11 which uses Python. The Binder tool also uses a configuration file.
The system uses a “+/-” for inclusion and omission of the three basic objects:
namespaces, classes, and functions. Binder’s configuration file can also alter
the functions used to bind the code. The user can specify a function which is
run in place of the default binding code.
PyBindGen
#########
https://pybindgen.readthedocs.io/en/latest/ and https://github.com/gjcarneiro/pybindgen
PyBindGen is a Python-only module that allows the specification of C++ modules
to wrap into PyBind11. It doesn’t rely on a configuration file to determine
what parts of the C++ code are wrapped but instead uses a Python script to
create the modules and add all objects. The compilation of the resultant code
is done via a “python setup.py” command and is what creates the PyBind11 code.
It does have some pygccxml integration. One mode of execution uses pygccxml to
parse C++ code and write the PyBind11 code into a separate file. The other
mode parses the header files but writes out the information into a PyBindGen
script.
.. _pycodestyle: https://pypi.org/project/pycodestyle/
.. _Copyright.txt: Copyright.txt
.. _`data.kitware.com`: https://data.kitware.com/#folder/57b5de948d777f10f2696370
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment