(r4) MuPDFWrap < Main

Tags: view all tags
---+!! C++ and Python APIs for !MuPDF

%TOC%

---++ Overview

---+++ API Stability

The C++ and Python !MuPDF APIs are currently an alpha release and liable to change.

---+++ The C++ !MuPDF API

   * ==fz_== exceptions are converted into C++ exceptions.
   * Functions and methods do not take ==fz_context== arguments. (Automatically-generated per-thread contexts are used internally.)
   * Provides C++ functions that wrap most ==fz_== and ==pdf_== functions.
   * Provides C++ classes that  wrap most ==fz_== and ==pdf_== structs.
   * Class methods provide access to most of the underlying C API functions (except for functions that don't take struct args such as ==fz_strlcpy()==).
   * Provides a small number of extensions beyond the basic C API:
      * Some generated classes have extra support for iteration.
      * Some custom methods/constructors.


---+++ The Python !MuPDF API

   * Generated from the C++ !MuPDF API's header files.
   * Allows implementation of mutool in Python - see ==mupdf:scripts/mutool.py== and ==mupdf:scripts/mutool_draw.py==.


---++ Building the C++ and Python !MuPDF APIs

Requirements:

   * Linux or !OpenBSD.
   * clang-python version 6 or 7. [For example Debian ==python-clang==, !OpenBSD ==py3-llvm==.]
   * python3-dev version 3.6 or later.
   * SWIG version 3 or 4.

Build MuPDF shared library, C++ and Python !MuPDF APIs, and run basic tests:

<verbatim>
    git clone --recursive git://git.ghostscript.com/mupdf.git
    cd mupdf
    ./scripts/mupdfwrap.py -b all -t
</verbatim>

As above but do a debug build:

<verbatim>
    ./scripts/mupdfwrap.py -d build/shared-debug -b all -t
</verbatim>

For more information:

   * Run ==./scripts/mupdfwrap.py -h==.
   * Read the doc-string at beginning of ==scripts/mupdfwrap.py==.


---++ Building auto-generated documentation

Build HTML documentation for the C, C++ and Python APIs (using Doxygen and pydoc):

<verbatim>
    ./scripts/mupdfwrap.py --doc all
</verbatim>

This will generate these documentation roots:

   * ==include/html/index.html== [C API]
   * ==platform/c++/include/html/index.html== [C++ API]
   * ==build/shared-release/mupdf.html== [Python API]

Note that the content is ultimately all generated from the !MuPDF C header file comments.


---++ Using the Python API

Run python code with:

    ==PYTHONPATH=build/shared-release LD_LIBRARY_PATH=build/shared-release==

(This enables Python to find the ==mupdf== module, and enables the system dynamic linker to find the shared libraries that implement the underlying C, C++ and Python !MuPDF APIs.)

Minimal Python code that uses the mupdf module:
<verbatim>
    import mupdf
    document = mupdf.Document('foo.pdf')
</verbatim>

A simple example Python test script (run by ==scripts/mupdfwrap.py -t==) is:
   * ==scripts/mupdfwrap_test.py==

More detailed usage of the Python API can be found in:
   * ==scripts/mutool.py==
   * ==scripts/mutool_draw.py==


---++ How the build works

Building of !MuPDF shared library:

   * Runs ==make== internally.

Generation of the C++ !MuPDF API:

   * Uses clang-python to parse !MuPDF's C API.
   * Generates C++ code that wraps the basic C interface.
   * Generates C++ classes for each ==fz_== struct, and uses various heuristics to define constructors, methods and static methods that call ==fz_()== functions.
   * C header file comments are copied into the generated C++ header files.

Generation of the Python !MuPDF API:

   * Based on the C++ !MuPDF API.
   * Uses SWIG to parse the C++ headers and generate C++ and Python code.
   * Defines some custom-written Python functions and methods.
   * If SWIG is version 4+, C++ comments are converted into Python doc-comments.


---++ Generated files

<verbatim>
    mupdf/
        build/
            shared-release/    [Files needed at runtime]
                libmupdf.so    [implements C MuPDF API]
                libmupdfcpp.so [implements C++ MuPDF API]
                mupdf.py       [implements Python MuPDF API]
                _mupdf.so      [implements Python MuPDF API internals]
            shared-debug/
                [as shared-release but debug build]
        platform/
            c++/
                include/
                    mupdf/ [C++ MuPDF API header files]
                        classes.h
                        exceptions.h
                        functions.h
                        internal.h
                implementation/
                    *.cpp [MuPDF C++ implementation files]
            python/
                [SWIG build files]
</verbatim>

---

 Please send any questions, comments or suggestions about this page to: julian.smith@artifex.com
Topic revision: r4 - 2020-08-26 - JulianSmith
~~Edit~~
~~Attach~~