Difference: MuPDFWrap (1 vs. 4)

Revision 42020-08-26 - JulianSmith

Line: 1 to 1
 
META TOPICPARENT name="JulianSmith"

C++ and Python APIs for MuPDF

Line: 25 to 25
 

The Python MuPDF API

  • Generated from the C++ MuPDF API's header files.
Changed:
<
<
  • Allow implementation of mutool in Python - see mupdf:scripts/mutool.py and mupdf:scripts/mutool_draw.py.
>
>
  • Allows implementation of mutool in Python - see mupdf:scripts/mutool.py and mupdf:scripts/mutool_draw.py.
 

Building the C++ and Python MuPDF APIs

Line: 37 to 37
 
  • python3-dev version 3.6 or later.
  • SWIG version 3 or 4.
Changed:
<
<
Build C++ and Python MuPDF APIs and run basic tests:
>
>
Build MuPDF shared library, C++ and Python MuPDF APIs, and run basic tests:
 
    git clone --recursive git://git.ghostscript.com/mupdf.git
Line: 82 to 82
  (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.)
Changed:
<
<
Minimal example Python code:
>
>
Minimal Python code that uses the mupdf module:
 
    import mupdf
    document = mupdf.Document('foo.pdf')
Changed:
<
<
Detailed usage of the Python API can be found in:
>
>
A simple example Python test script (run by scripts/mupdfwrap.py -t) is:
  • scripts/mupdfwrap_test.py
 
Added:
>
>
More detailed usage of the Python API can be found in:
 
  • scripts/mutool.py
  • scripts/mutool_draw.py
Line: 131 to 132
  platform/ c++/ include/
Changed:
<
<
mupdf/ [C++ MuPDF API]
>
>
mupdf/ [C++ MuPDF API header files]
  classes.h exceptions.h functions.h internal.h
Deleted:
<
<

Other internal generated files:

    mupdf/
        build/
        platform/
            c++/
  implementation/
Changed:
<
<
*.cpp [MuPDF C++ implementation]
>
>
*.cpp [MuPDF C++ implementation files]
  python/
Changed:
<
<
[SWIG files]
>
>
[SWIG build files]
 


Revision 32020-08-26 - JulianSmith

Line: 1 to 1
 
META TOPICPARENT name="JulianSmith"

C++ and Python APIs for MuPDF

Line: 8 to 8
 

API Stability

Changed:
<
<
The C++ and Python MuPDF APIs are currently liable to change.
>
>
The C++ and Python MuPDF APIs are currently an alpha release and liable to change.
 

The C++ MuPDF API

Revision 22020-08-26 - JulianSmith

Line: 1 to 1
 
META TOPICPARENT name="JulianSmith"
Changed:
<
<

C++ and Python APIs for MuPDF.

>
>

C++ and Python APIs for MuPDF

 
Changed:
<
<

Overview:

>
>

Overview

 
Changed:
<
<

The C++ MuPDF API:

>
>

API Stability

 
Changed:
<
<
  • All C++ API code converts fz_ exceptions into C++ exceptions.
  • All C++ API code uses auto-generated internal per-thread fz_context and do not take fz_context args.
  • We generate C++ wrapper functions for most fz_ and pdf_ functions.
  • We generate C++ class wrappers for most fz_ and pdf_ structs.
  • Class methods provide access to most of the underlying C API functions (except for functions don't take struct args, e.g. fz_strlcpy()).
  • We auto-detect fz_ and pdf_ fns suitable for wrapping as constructors, methods or static methods.
  • We add a small number of extensions beyond the basic C API:
>
>
The C++ and Python MuPDF APIs are currently 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.
Changed:
<
<
    • We add some custom methods/constructors.
>
>
    • Some custom methods/constructors.
 
Changed:
<
<

The Python MuPDF API:

>
>

The Python MuPDF API

 
Changed:
<
<
  • Python MuPDF API is generated from the C++ MuPDF API's header files.
  • Python MuPDF API is enough to allow implementation of mutool in Python - see mupdf:scripts/mutool.py and mupdf:scripts/mutool_draw.py.
>
>
  • Generated from the C++ MuPDF API's header files.
  • Allow implementation of mutool in Python - see mupdf:scripts/mutool.py and mupdf:scripts/mutool_draw.py.
 
Changed:
<
<

Building the C++ and Python MuPDF APIs:

>
>

Building the C++ and Python MuPDF APIs

 
Changed:
<
<
We require:
  • Linux or OpenBSD.
  • python-clang (version 6 or 7)
  • python3-dev (version 3.6 or later)
  • swig (version 3 or 4)
>
>
Requirements:
 
Changed:
<
<
All building is done with the scripts/mupdfwrap.py script.
>
>
  • 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.
 
Changed:
<
<
Build C++ and Python MuPDF APIs and run basic tests with:
>
>
Build C++ and Python MuPDF APIs and run basic tests:

    git clone --recursive git://git.ghostscript.com/mupdf.git
  cd mupdf ./scripts/mupdfwrap.py -b all -t
Changed:
<
<
>
>
 
Changed:
<
<
Debug build:
    cd mupdf
>
>
As above but do a debug build:
  ./scripts/mupdfwrap.py -d build/shared-debug -b all -t
Changed:
<
<
>
>

For more information:

  • Run ./scripts/mupdfwrap.py -h.
  • Read the doc-string at beginning of scripts/mupdfwrap.py.
 
Changed:
<
<
For more details, run ./scripts/mupdfwrap.py -h to see help, or look at the doc-string at beginning of the script directly.
>
>

Building auto-generated documentation

 
Changed:
<
<

Using the Python API:

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

    ./scripts/mupdfwrap.py --doc all

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

Changed:
<
<
(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.)
>
>
(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.)
 
Changed:
<
<
Example Python code:
>
>
Minimal example Python code:
 
Changed:
<
<
>
>
  import mupdf
Changed:
<
<
document = mupdf.Document("foo.pdf")
>
>
document = mupdf.Document('foo.pdf')
  Detailed usage of the Python API can be found in:
Line: 76 to 95
 
  • scripts/mutool_draw.py
Changed:
<
<

How the build works:

>
>

How the build works

 
Changed:
<
<
Building of MuPDF shared library:
>
>
Building of MuPDF shared library:
 
Changed:
<
<
  • Built by mupdfwrap.py -b m (also included in -b all).
  • This runs make internally.
>
>
  • Runs make internally.
 
Changed:
<
<
mupdfwrap.py 's generation of the C++ MuPDF API:
>
>
Generation of the C++ MuPDF API:
 
Changed:
<
<
  • Uses clang-python to parse MuPDF's C API.
>
>
  • Uses clang-python to parse MuPDF's C API.
 
  • Generates C++ code that wraps the basic C interface.
Changed:
<
<
  • Generates C++ classes for each fz_ struct, and uses various heuristics to define methods that call fz_() functions.
>
>
  • 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.
Changed:
<
<
mupdfwrap.py 's generation of the Python MuPDF API:
>
>
Generation of the Python MuPDF API:
 
Changed:
<
<
  • Based on the C++ 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.
Changed:
<
<
  • If swig is version 4+, we tell it to propagate C++ comments into the generated Python.
>
>
  • If SWIG is version 4+, C++ comments are converted into Python doc-comments.
 
Changed:
<
<

Generated files:

>
>

Generated files

 
Changed:
<
<
>
>
  mupdf/ build/
Changed:
<
<
shared-release/ [Files needed at runtime.]
>
>
shared-release/ [Files needed at runtime]
  libmupdf.so [implements C MuPDF API] libmupdfcpp.so [implements C++ MuPDF API] mupdf.py [implements Python MuPDF API]
Line: 119 to 136
  exceptions.h functions.h internal.h
Changed:
<
<
>
>
  Other internal generated files:
Changed:
<
<
>
>
  mupdf/ build/ platform/ c++/ implementation/
Changed:
<
<
*.cpp [MuPDF C++ implementation.]
>
>
*.cpp [MuPDF C++ implementation]
  python/
Changed:
<
<
[SWIG files.]
>
>
[SWIG files]
 
Changed:
<
<
>
>
 

Please send any questions, comments or suggestions about this page to: julian.smith@artifex.com

Added:
>
>
META TOPICMOVED by="JulianSmith" date="1598431398" from="Main.MupdfWrappers" to="Main.MuPDFWrap"

Revision 12020-08-25 - JulianSmith

Line: 1 to 1
Added:
>
>
META TOPICPARENT name="JulianSmith"

C++ and Python APIs for MuPDF.

Overview:

The C++ MuPDF API:

  • All C++ API code converts fz_ exceptions into C++ exceptions.
  • All C++ API code uses auto-generated internal per-thread fz_context and do not take fz_context args.
  • We generate C++ wrapper functions for most fz_ and pdf_ functions.
  • We generate C++ class wrappers for most fz_ and pdf_ structs.
  • Class methods provide access to most of the underlying C API functions (except for functions don't take struct args, e.g. fz_strlcpy()).
  • We auto-detect fz_ and pdf_ fns suitable for wrapping as constructors, methods or static methods.
  • We add a small number of extensions beyond the basic C API:
    • Some generated classes have extra support for iteration.
    • We add some custom methods/constructors.

The Python MuPDF API:

  • Python MuPDF API is generated from the C++ MuPDF API's header files.
  • Python MuPDF API is enough to allow implementation of mutool in Python - see mupdf:scripts/mutool.py and mupdf:scripts/mutool_draw.py.

Building the C++ and Python MuPDF APIs:

We require:

  • Linux or OpenBSD.
  • python-clang (version 6 or 7)
  • python3-dev (version 3.6 or later)
  • swig (version 3 or 4)

All building is done with the scripts/mupdfwrap.py script.

Build C++ and Python MuPDF APIs and run basic tests with:

    cd mupdf
    ./scripts/mupdfwrap.py -b all -t

Debug build:

    cd mupdf
    ./scripts/mupdfwrap.py -d build/shared-debug -b all -t

For more details, run ./scripts/mupdfwrap.py -h to see help, or look at the doc-string at beginning of the script directly.

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

Example Python code:

    import mupdf
    document = mupdf.Document("foo.pdf")

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:

  • Built by mupdfwrap.py -b m (also included in -b all).
  • This runs make internally.

mupdfwrap.py 's 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 methods that call fz_() functions.
  • C header file comments are copied into the generated C++ header files.

mupdfwrap.py 's 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+, we tell it to propagate C++ comments into the generated Python.

Generated files:

    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]
                        classes.h
                        exceptions.h
                        functions.h
                        internal.h

Other internal generated files:

    mupdf/
        build/
        platform/
            c++/
                implementation/
                    *.cpp [MuPDF C++ implementation.]
            python/
                [SWIG files.]


Please send any questions, comments or suggestions about this page to: julian.smith@artifex.com

 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright 2014 Artifex Software Inc