mutool

Short:        MuPDF command-line tool (mutool) for AmigaOS 4.1
Author:       MuPDF: Artifex Software, Inc. and contributors / AmigaOS4 port:
Falke_34
Uploader:     Falke_34
Type:         text/show
Version:      1.27.2
Architecture: ppc-amigaos >= 4.1
Distribution: Aminet, OS4Depot
Requires:     AmigaOS 4.1 or higher, newlib

----------------------------------------------------------------------

DESCRIPTION

mutool is the official command-line tool of MuPDF, a lightweight and
fast PDF, XPS, EPUB, CBZ and image rendering library. This package
contains a native AmigaOS 4.1 (PowerPC, newlib) port of mutool,
cross-compiled from the original MuPDF 1.27.2 sources.

mutool can:

  - render PDF, EPUB, XPS, CBZ, FB2, MOBI and image documents to
    PNG, PNM, PAM, PGM, PBM, PWG, PCL and PS
  - convert between document formats (e.g. EPUB -> PDF, EPUB -> DOCX,
    PDF -> SVG, any supported format -> plain text)
  - extract text, structured text and metadata from PDF documents
  - display PDF document info (mutool info, PDF only)
  - merge, split, clean and repair PDF files
  - decode JPEG2000 (JP2/JPX) images via the bundled OpenJPEG library

This build was created primarily to provide a stable MuPDF library
foundation (libmupdf.a + headers) for AmigaOS4 application development,
e.g. as used by the AmiBookReader e-book reader.


----------------------------------------------------------------------

CONTENTS OF THE ARCHIVE

  bin/mutool                 - the command-line tool, stripped
  lib/libmupdf.a              - MuPDF core library
  lib/libmupdf-third.a        - bundled third-party libraries
                                 (zlib, libjpeg, freetype, harfbuzz,
                                  openjpeg, jbig2dec, lcms2, mujs,
                                  gumbo-parser, brotli, extract)
  lib/libmupdf-threads.a       - threading helper library
  lib/libmupdf-pkcs7.a         - PKCS#7 / digital signature helper
                                 library (OpenSSL based)
  include/mupdf/...            - C headers for application development
                                  (#include <mupdf/fitz.h> etc.)

The lib/ and include/ directories are provided so that other AmigaOS4
developers can link MuPDF into their own applications without having
to set up the whole cross-compile toolchain themselves.


----------------------------------------------------------------------

INSTALLATION

Copy bin/mutool to a directory in your search path, e.g.:

    Copy bin/mutool C:mutool

For application development, copy lib/ and include/ to your SDK
directory and link against them, e.g.:

    gcc ... -Ipath/include -Lpath/lib 
        -Wl,--start-group -lmupdf -lmupdf-third -lmupdf-threads 
        -lmupdf-pkcs7 -Wl,--end-group -lz -lm -lpthread -lauto


----------------------------------------------------------------------

USAGE EXAMPLES

  Show mutool version:
      mutool -v

  Show PDF document info (PDF only):
      mutool info document.pdf

  Render all pages of a document to PNG (one file per page):
      mutool draw -o page%d.png -r 150 document.pdf

  Render a single page to PNG:
      mutool draw -o page.png -r 150 document.pdf 1

  Extract plain text from any supported document (UTF-8):
      mutool draw -F text -o output.txt document.pdf

  Convert EPUB to PDF:
      mutool convert -o output.pdf book.epub

  Convert text/EPUB to DOCX (openable in word processors and in
  AmiBookReader):
      mutool convert -o output.docx book.epub

  Decode a JPEG2000 (JP2) image to PNG:
      mutool convert -o output.png image.jp2

NOTE: "mutool info" only supports PDF documents (it calls the PDF
parser directly). For other formats (EPUB, FB2, MOBI, CBZ, images,
etc.) use "mutool draw" or "mutool convert" instead, which use MuPDF's
generic document handler and support all of the formats listed above.


----------------------------------------------------------------------

TESTED ON

  - AmigaOS 4.1 FE, QEMU (Pegasos2/AmigaOne emulation)
  - PDF rendering (text + embedded JPEG/JPX images), all pages
  - EPUB3 rendering, pagination and text extraction
  - JPEG2000 (JP2) decoding via convert
  - DOCX output, reopened successfully in AmiBookReader

A "premature end of file in jpeg" warning may appear for individual
malformed embedded images in some PDF files; this does not affect
the rest of the document and is not specific to this AmigaOS port.


----------------------------------------------------------------------

BUILD NOTES (AmigaOS4-SPECIFIC PATCHES)

This is a cross-compiled build (Ubuntu host, Docker, GCC 11,
ppc-amigaos-gcc, -mcrt=newlib), using the standard MuPDF 1.27.2
release sources with the following AmigaOS4/newlib compatibility
patches applied automatically by the build script:

  1. Header fixes:
     - <sys/time.h> is not available; the include is removed.
     - <memory.h> is replaced with <string.h>.
     - u_int8_t/u_int16_t/u_int32_t are mapped to the standard
       uint8_t/uint16_t/uint32_t types via -D defines.

  2. OpenJPEG big-endian fix:
     The bundled OpenJPEG library does not auto-detect PowerPC's
     big-endian byte order during cross-compilation. opj_config.h
     is patched to force OPJ_BIG_ENDIAN=1, which is required for
     correct JPEG2000 (JP2/JPX) decoding on PPC.

  3. timegm() replacement:
     newlib does not provide timegm(). A small, portable, timezone-
     independent replacement (my_timegm) is injected into every
     source file that calls timegm() (used for parsing PDF date
     metadata).

Build configuration:
     HAVE_X11=no HAVE_GLUT=no HAVE_WIN32=no HAVE_LIBCRYPTO=no
     HAVE_OBJCOPY=no BUNDLED_OPENJPEG=yes build=release
     FZ_ENABLE_JS=0 FZ_ENABLE_UI=0 FZ_ENABLE_TRUETYPE=1
     TOFU_NOTO=1 TOFU_CJK=1

JavaScript support (mujs) and the GL/X11/Win32 UI frontends are
disabled, as they are not applicable/available on AmigaOS4. Built-in
TrueType fonts (Noto fallback fonts incl. CJK) are enabled for text
rendering without external font dependencies.


----------------------------------------------------------------------

LICENSE / SOURCE CODE

MuPDF is Copyright (C) Artifex Software, Inc. and is licensed under
the GNU Affero General Public License (AGPL) version 3, or under a
commercial license available from Artifex Software.

The unmodified original MuPDF 1.27.2 source code is available from:

    https://mupdf.com/downloads/

In accordance with the AGPL, the AmigaOS4-specific patches applied
during this build are documented above and the full build script
used to produce this package is included with this distribution
(or available from the uploader on request), so that anyone can
reproduce this build from the original MuPDF sources.

This package itself (the AmigaOS4 binaries and the build script) is
provided free of charge for the AmigaOS4 community. No warranty is
given; use at your own risk.


----------------------------------------------------------------------

CREDITS

  - Artifex Software, Inc. and the MuPDF contributors for MuPDF
  - walkero for the amigagccondocker AmigaOS4 cross-compile toolchain
  - Falke_34 - AmigaOS4 cross-compile build script and testing