Android Viewer Manual

Android Viewer Manual

Prerequisites for Building a Viewer
Building a Viewer
Running a Viewer
Releasing a Viewer
Building a Library
Setting Up the Subproject
Adding the JNI Library
Adding the Java Library

The MuPDF AGPL license is for developers who wish to share their entire application source code with the open-source community under the terms of AGPL. As soon as you want to use MuPDF in a closed source, proprietary environment, OR need technical support from Artifex, you must purchase an Artifex Commercial License.

More information regarding licensing may be found on the Artifex licensing page. If you are uncertain as to whether you can use the AGPL release or require a commercial license, please contact us at Artifex Sales and we’ll be happy to help.


Prerequisites for Building a Viewer

You must have a working Android development environment, consisting of the Android SDK and the Android NDK. The easiest way is to download and install the SDK and NDK from Android Studio. Make sure that the Android/SDK/tools and Android/SDK/NDK-bundle directories are on your path.

You will also need Oracle’s Java JDK (OpenJDK is not compatible with Android), the Apache Ant build system, as well as the Git, GNU Make, and a C compiler.

If everything is working, you should be able to run these commands from the command line:

Android SDK tools: android, emulator, and adb.
Android NDK tools: ndk-build.
Oracle Java JDK 8: java, and javac.
Apache Ant: ant.
Git: git.
GNU Make: make, or gmake.
C compiler: cc, gcc, or clang.


Building a Viewer

Download the project using Git (and don’t forget the –recursive flag):

If all tools have been installed as per the prerequisites, build the app using make:

The makefile will take care of setting up the Android project and configuration files. This is, of course, assuming that you have set up the prerequisites properly.


Running a Viewer

To run the app in the Android emulator, first, you’ll need to set up an “Android Virtual Device” for the emulator. Run “android avd” and create a new device. You can also use Android Studio to set up a virtual device. Use the x86 ABI for best emulator performance.

Then launch the emulator, or connect a device with USB debugging enabled:

Then copy some test files to the device:

Then install the app on the device:

In order to build, install, and launch the app in one step:

To see the error and debugging message log:


Releasing a Viewer

To release you MUST first change the package name. Do NOT use the com.artifex domain for your custom app!

Change all references to into in the Java source files and XML resources.

In order to sign a release build, you will need to create a key and a key store.

Then add the following entries to

If your keystore has been set up properly, you can now build a release APK.


Building a Library for Android

The MuPDF library in Android is based on JNI to access the native C library through a layer of Java classes. The MuPDF Java library provides platform independent (i.e. both Android and desktop Java) low-level access to MuPDF functionality.

The MuPDF Java library does not provide any Android specific components or widgets – build those yourself or use one of the example viewers as a start.

In order to use the MuPDF library in Android, you must thus add two components to your build system: the JNI library, and the Java library.


Setting Up the MuPDF Subproject

Set up your Android project as you wish, and then add the MuPDF repository as a directory somewhere in your project. If you’re using git, you can use a submodule:

You can also unpack a release tarball archive in your source directory.

We’ll assume you name the MuPDF project directory ‘libmupdf’
Use your host compiler to run the ‘generate’ step in the MuPDF project:


Adding the JNI Library

Add a NDK-build step to your project, using the file from MuPDF.

If compiling manually, set the appropriate variables yourself:

If using gradle, add an externalNativeBuild section in the Android section in the build.gradle file:


Adding the Java Library

You’ll also need to include the Java classes that bind to the JNI library.If you’re using ant, add the ‘libmupdf/platform/java/src’ directory to the list of source directories. For example, set the variables in an file:

If using gradle, add the ‘libmupdf/platform/java/src’ directory to the list of source directories in the build.gradle file: