• MuPDFWrap

• The C++ API is built by mupdf:scripts/mupdfwrap.py. It requires clang-6 or clang-7, and python-clang.

• Building the Python API requires swig-3 or swig-4.

• 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.

• 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().

• 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.

• https://ghostscript.com/~julian/mupdf/include/html/index.html
• https://ghostscript.com/~julian/mupdf/platform/c++/include/html/index.html

• https://ghostscript.com/~julian/mupdf/build/shared-release/mupdf.html

Auto-generated C++ and Python APIs for mupdf.

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 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.

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)

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.

• We provide access via wrapper classes to 686 fz_*() fns.
• There are a total of 888 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.
• We work with swig-3 or swig-4.
• We work with clang-6 or clang-7.
• We work on peeved and jules-laptop.

• 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

Status

As of 2020-4-24:

• We generate 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 wrappers for fz_*() fns.
• We add various custom methods/constructors.
• We provide access via wrapper classes to 715 fz_*() fns.
• There are a total of 935 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.

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.

Files

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

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

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

Integration with mupdf git.

    mupdf/
        build/
            shared/
                libmupdf.so  [generated file]
                libmupdfcpp.so [generated file, implements C++ API]
        platform/
            c++/
                Makefile
                implementation/
                    *.cpp [generated files]
                include/
                    mupdf/
                        *.h [generated files]
            python/
                Makefile
                mudf.py [generated file, implements Python API]
                _mupdf.so [generated file, implements Python API internals]

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

To build, ensure that julian-tools is checked out next to mupdf, then:

    cd mupdf/platform/python
    make
    make test

The makefiles build things by running ../../../julian-tools/mupdfwrap.py.

Have also added crude support for building mupdf as a shared object, which is required for integrating with the SWIG python module. At the moment, mupdfwrap.py drives this to build mupdf.so.

See:

• https://git.ghostscript.com/?p=user/julian/julian-tools.git;a=blob;f=mutool.py;hb=HEAD
• https://git.ghostscript.com/?p=user/julian/julian-tools.git;a=blob;f=mutool_draw.py;hb=HEAD

mutool.py

Python implementation of mutool. as of 2020-4-1, this only implements some of the "trace" sub-command. See:

* https://git.ghostscript.com/?p=user/julian/julian-tools.git;a=blob;f=mutool.py;hb=HEAD

• https://ghostscript.com/~julian/mupdf_test/test.py.html

• https://ghostscript.com/~julian/mupdf_test/test.py.txt
• https://ghostscript.com/~julian/mupdf_test/test_out.txt

• [Old] Using lower-case and underscores: https://ghostscript.com/~julian/mupdf_test0/

• See test_mupdfcpp_swig() function for example python code that uses the generated API.
• See "Todo:" section in comment near top, for status of various todo items.

• Using lower-case and underscores: https://ghostscript.com/~julian/mupdf_test0/

• https://git.ghostscript.com/?p=user/julian/julian-tools.git;a=blob;f=mupdfwrap.py;hb=HEAD

• https://git.ghostscript.com/?p=user/julian/julian-tools.git;a=blob;f=test_mupdfpy.py.py;hb=HEAD

• https://ghostscript.com/~julian/mupdf_test/

Auto-generated mupdf C++ wrappers

Article text.

Standard wrappers:

• https://ghostscript.com/~julian/mupdf_wrap.cpp.txt
• https://ghostscript.com/~julian/mupdf_wrap.h.txt

Using class template for exceptions:

• https://ghostscript.com/~julian/mupdf_wrapt.cpp.txt
• https://ghostscript.com/~julian/mupdf_wrapt.h.txt

These were generated by:

• https://git.ghostscript.com/?p=user/julian/julian-tools.git;a=blob;f=jclang.py;hb=HEAD

-- Julian Smith - 2020-03-04

Comments

<--/commentPlugin-->