(r17) MupdfCppWrappers < Main

Tags: view all tags
---+ Auto-generated C++ and Python APIs for mupdf.

---++ Status

As of 2020-5-4:

---+++ C++

   * C++ API is generated by mupdf:scripts/mupdfwrap.py, which uses python-clang.
   * We require clang-6 or clang-7.
   * We generate C++ class wrappers for all fz structs.
   * We auto-detect fz_*() 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.
   * We provide access via wrapper classes to 690 fz_*() fns.
   * There are a total of 890 fz_*() functions. Most of the omitted functions don't take struct args, e.g. fz_strlcpy(). Of the remaining, some use fz_* enums (which we don't yet wrap); see https://ghostscript.com/~julian/mupdf/platform/c++/fn_usage.txt for more information.

---+++ 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.
   * We work with 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 propogate them into generated header files.
   * If swig is version 4+, we tell it to propogate comments into generated mupdf.py.

Here are Doxygen html representations of the mupdf C API and the generated mupdf C++ API:

   * https://ghostscript.com/~julian/doxygen/mupdf/index.html
   * https://ghostscript.com/~julian/doxygen/mupdfcpp/index.html

And pydoc html representation of the generated mupdf.py API:

   * https://ghostscript.com/~julian/pydoc/mupdf.html


---++ mutool.py

mudpdf:scripts/mutool*.py are a Python re-implementation of the mutool application.

They do not use threads, or the include/mupdf/pdf/ functionality.


---++ Files

Auto-generated C++ headers and implementation files, plus test outputs (.html files have syntax-colouring):

   * https://ghostscript.com/~julian/mupdf/platform/c++/
   * https://ghostscript.com/~julian/mupdf/platform/python

Information about fz_*() fns that are not in the class-based API:

   * https://ghostscript.com/~julian/mupdf/platform/c++/fn_usage.txt

These were generated by the mupdfwrap.py programme, which also runs g++ and SWIG to generate a Python module that gives a Python API:

   * https://git.ghostscript.com/?p=user/julian/mupdf.git;a=blob;f=scripts/mupdfwrap.py;hb=HEAD

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.

<literal>
<pre>
    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
</pre>
</literal>

See:

   * https://git.ghostscript.com/?p=user/julian/mupdf.git;a=summary



To build:

<literal>
<pre>
    cd mupdf/
    ./scripts/mupdfwrap.py -b all -t
</pre>
</literal>




----    

-- %USERSIG{JulianSmith - 2020-03-04}%

---++ Comments

%COMMENT%
Topic revision: r17 - 2020-05-05 - JulianSmith
~~Edit~~
~~Attach~~