Auto-generated C++ and Python APIs for mupdf.
Status
As of 2020-5-11:
C++
- We generate C++ wrapper functions for most fz_ and pdf_ functions. These wrapper convert fz_ exceptions into C++ exceptions, and use auto-generated per-thread fz_context's.
- We generate C++ class wrappers for most fz_ and pdf_ structs.
- We auto-detect fz_*() and pdf_*() fns suitable for wrapping as constructors, methods or static methods.
- Some generated classes have auto-generated support for iteration.
- We add various custom methods/constructors.
- Wrapper class constructors and methods provide access to 1270 fz_*() and pdf_*() fns, out of a total of 1513 wrapped fz_*() and pdf_*() functions. Most of the omitted functions don't take struct args, e.g. fz_strlcpy().
- The C++ API is built by mupdf:scripts/mupdfwrap.py. It requires clang-6 or clang-7, and python-clang.
Python
- Python API is generated by running SWIG on the C++ API's header files.
- Python API is enough to allow implementation of mutool in Python - see mupdf:scripts/mutool.py and mupdf:scripts/mutool_draw.py.
- Building the Python API requires swig-3 or swig-4.
General
- We work on nuc1 and peeved and jules-laptop.
- We require:
- python-clang (version 6 or 7)
- python3-dev (version 3.6 or later)
- swig (version 3 or 4)
Comments
- We use clang to extract doxygen-style comments, and propagate them into generated header files.
- If swig is version 4+, we tell it to propagate comments into the generated mupdf.py.
Here are Doxygen html representations of the mupdf C API and the generated mupdf C++ API:
And pydoc html representation of the generated mupdf.py API:
mutool.py
mudpdf:scripts/mutool*.py are an incomplete Python re-implementation of the mutool application.
Files
Auto-generated C++ headers and implementation files, plus test outputs (.html files have syntax-colouring):
Information about fz_*() and pdf_*() fns that are not in the class-based API:
These were generated by the mupdfwrap.py programme, which also runs g++ and SWIG to generate a Python module that gives a Python API:
The generated Python module is tested by the (rather hacky) test_mupdfcpp_swig() function in mupdfwrap.py. For convenience, this function and its output can be viewed in
https://ghostscript.com/~julian/mupdf/platform/python
.
Integration with mupdf git.
mupdf/
build/
shared-release/
libmupdf.so [generated file]
libmupdfcpp.so [generated file, implements C++ API]
mupdf.py [generated file, implements Python API]
_mupdf.so [generated file, implements Python API internals]
shared-debug/
libmupdf.so
libmupdfcpp.so [implements C++ API]
mupdf.py [implements Python API]
_mupdf.so [implements Python API internals]
platform/
c++/
implementation/
*.cpp [generated files]
include/
mupdf/
*.h [generated files]
python/
mupdfcpp_swig.cpp [generated by SWIG]
mupdf_swig.i [generated by mupdfwraw.pynput to SWIG]
scripts/
mupdfwrap.py
jlib.py
mutool.py
mutool_draw.py
See:
To build:
cd mupdf/
./scripts/mupdfwrap.py -b all -t
--
Julian Smith - 2020-03-04
Comments