----------------------------------------------------------------------
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 3.x (68k, libnix) port of mutool,
cross-compiled from the original MuPDF 1.28.2 sources.
This is the classic 68k sibling of the AmigaOS 4.1/PowerPC mutool
package. It is a single, headless (no GUI) command-line tool with no
special hardware requirements beyond a 68020 or better - it runs
happily on a plain 68020/68030 without an FPU (soft-float), and does
not require any graphics card or cybergraphics.library.
Unlike the AmigaOS4/PPC build, this 68k build has the following
features disabled or unavailable, due to constraints of the libnix
C runtime and the bebbo m68k-amigaos-gcc 6 cross-compiler used to
build it (see BUILD NOTES below for details):
- No JavaScript (mujs) support - PDF forms/scripts that rely on
JavaScript will not execute.
- No ICC colour management (HAVE_ICC=no) - colour profiles embedded
in documents are ignored.
- No multi-threading (HAVE_PTHREAD=no) - rendering is always
single-threaded.
- No libcurl/HTTP(S) support - mutool cannot open documents
directly from a URL.
- No barcode (ZXing) support.
- Only Base14 (URW) fonts are built in - characters outside Base14
coverage (CJK, most Unicode Extended Latin, emoji, etc.) in
documents without their own embedded fonts will show as "tofu"
placeholder boxes. Unlike the PPC/AmigaOS4 package, there is no
separate full-Noto-fallback variant of this 68k build.
mutool can still:
- render PDF, EPUB, XPS, CBZ, FB2, MOBI, Markdown 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
The lib/ and include/ directories are provided so that other AmigaOS
3.x developers can link MuPDF into their own applications without
having to set up the whole cross-compile toolchain themselves.
(e.g. as used by the AmiBookReader e-book reader)
----------------------------------------------------------------------
CONTENTS OF THE ARCHIVE
mupdf-amiga3/
bin/mutool - the command-line tool, stripped
lib/libmupdf.a - MuPDF core library
lib/libmupdf-third.a - bundled third-party libraries
(zlib, libjpeg, freetype, openjpeg,
jbig2dec)
lib/libmupdf-threads.a - threading helper library (present for
ABI completeness; built with
HAVE_PTHREAD=no, so it is a no-op on
this platform - see above)
lib/libmupdf-pkcs7.a - PKCS#7 / digital signature helper
library (signature verification
disabled at build time, see BUILD
NOTES; included for ABI completeness)
include/mupdf/... - C headers for application development
(#include <mupdf/fitz.h> etc.)
----------------------------------------------------------------------
INSTALLATION
Copy bin/mutool to a directory in your search path, e.g.:
Copy mupdf-amiga3/bin/mutool C:mutool
For application development, copy lib/ and include/ to your SDK
directory and link against them, e.g.:
m68k-amigaos-gcc ... -Ipath/include -Lpath/lib \
-Wl,--start-group -lmupdf -lmupdf-third -lmupdf-threads \
-lmupdf-pkcs7 -Wl,--end-group -lm
----------------------------------------------------------------------
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, Markdown,
images, etc.) use "mutool draw" or "mutool convert" instead, which
use MuPDF's generic document handler and support all of the formats
listed above.
----------------------------------------------------------------------
KNOWN ISSUES
- Suspected -O2 zlib miscompile in bebbo's m68k-amigaos-gcc 6:
during testing, "mutool extract" occasionally failed to correctly
decompress FlateDecode font streams and PNG IDAT data ("zlib
error: incorrect data check") when zlib's own sources were built
at -O2, while the exact same MuPDF source built for AmigaOS4/PPC
did not show this problem - pointing at a compiler bug rather
than a data/format issue. As a precaution, this build forces
thirdparty/zlib/*.c to compile at -O0 while the rest of MuPDF
stays at -O2 (see BUILD NOTES). No further zlib-related
decompression failures were observed after this change, but if
you do run into one, please report it together with the
offending file.
- No JavaScript, ICC colour management, multi-threading, libcurl/
HTTP or barcode support - see DESCRIPTION above.
- Only Base14 fonts are built in; documents without embedded fonts
that need characters outside Base14 coverage will show "tofu"
placeholder boxes instead of the correct glyph.
----------------------------------------------------------------------
BUILD NOTES (AmigaOS3/68k-SPECIFIC PATCHES)
This is a cross-compiled build (Docker, amigadev/crosstools:
m68k-amigaos - bebbo's GCC 6 m68k-amigaos-gcc, libnix), using the
standard MuPDF 1.28.2 release sources with the following AmigaOS3/
libnix compatibility patches applied automatically by the build
script:
1. Header fixes:
- <sys/time.h> is not available in libnix; the include is
commented out.
- <memory.h> is replaced with <string.h>.
- <pthread.h> is commented out (no pthread on classic AmigaOS).
- u_int8_t/u_int16_t/u_int32_t are mapped to the standard
uint8_t/uint16_t/uint32_t types via compiler -D defines.
2. OpenJPEG big-endian fix:
The bundled OpenJPEG library does not auto-detect 68k'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 m68k.
3. Missing libc function stubs:
libnix does not provide timegm(), getpagesize(), realpath() or
strnlen(). Small, portable replacements are injected directly
into every source file that calls them:
- timegm(): a self-contained, timezone-independent
implementation.
- getpagesize(): replaced with the constant 4096.
- realpath(): a getcwd()-based fallback (no symlinks on
AmigaOS, so this is suffient for fz_realpath()'s needs).
- strnlen(): a straightforward bounded-length implementation.
gettimeofday() (needed by mutool's -timing code, but declared in
the <sys/time.h> commented out in step 1) is likewise replaced
with a clock()-based approximation.
4. zlib -O2 workaround:
See KNOWN ISSUES above. thirdparty/zlib/*.c is compiled at -O0;
the rest of MuPDF stays at the normal -O2.
5. ZXing barcode stub:
zxingbarcode.cpp is replaced with an empty stub, since the
external ZXing-C++ library is not available for this toolchain
and -DFZ_ENABLE_BARCODE=0 alone does not remove the build
dependency.
Build configuration:
HAVE_X11=no HAVE_GLUT=no HAVE_WIN32=no HAVE_LIBCRYPTO=no
HAVE_OBJCOPY=no HAVE_PTHREAD=no HAVE_LCMS2=no HAVE_ICC=no
BUNDLED_OPENJPEG=yes build=release
FZ_ENABLE_JS=0 FZ_ENABLE_UI=0 FZ_ENABLE_BARCODE=0 FZ_ENABLE_ICC=0
TOFU_NOTO=1 TOFU_CJK=1
CFLAGS: -m68020-60 -noixemul -msoft-float -O2 -fno-strict-aliasing
(runs on 68020 through 68060, no FPU required; for an
FPU-only build add -m68881 and drop -msoft-float)
PDF digital signature verification (PKCS#7 via OpenSSL) is disabled
(HAVE_LIBCRYPTO=no), same reasoning as the AmigaOS4/PPC package: a
cross-compiled OpenSSL static library for m68k-amigaos would be
required to enable this feature, and AmiSSL's interface-pointer-based
API is not link-compatible with MuPDF's direct OpenSSL C API calls.
----------------------------------------------------------------------
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.28.2 source code is available from:
https://mupdf.com/downloads/
In accordance with the AGPL, the AmigaOS3/68k-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 AmigaOS3 68k binaries and the build script)
is provided free of charge for the AmigaOS community. No warranty is
given; use at your own risk.
----------------------------------------------------------------------
CREDITS
- Artifex Software, Inc. and the MuPDF contributors for MuPDF
- amigadev/crosstools (bebbo) for the m68k-amigaos-gcc cross-
compile toolchain and Docker image
- Falke_34 - AmigaOS3/68k cross-compile build script and testing
|
aminet net>