Tor Andersson | be8322d | 2017-10-20 14:45:42 +0200 | [diff] [blame] | 1 | # MuPDF Android Viewer |
| 2 | |
| 3 | This project is a simplified variant of the full MuPDF Android app that only |
| 4 | supports viewing documents. The annotation editing and form filling features |
| 5 | are not present here. |
| 6 | |
| 7 | This project builds both a viewer library and a viewer application. |
| 8 | The viewer library can be used to view PDF and other documents. |
| 9 | |
| 10 | The application is a simple file chooser that shows a list of documents on the |
| 11 | external storage on your device, and hands off the selected file to the viewer |
| 12 | library. |
| 13 | |
| 14 | ## License |
| 15 | |
| 16 | MuPDF is Copyright (c) 2006-2017 Artifex Software, Inc. |
| 17 | |
| 18 | This program is free software: you can redistribute it and/or modify it under |
| 19 | the terms of the GNU Affero General Public License as published by the Free |
| 20 | Software Foundation, either version 3 of the License, or (at your option) any |
| 21 | later version. |
| 22 | |
| 23 | This program is distributed in the hope that it will be useful, but WITHOUT ANY |
| 24 | WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A |
| 25 | PARTICULAR PURPOSE. See the GNU General Public License for more details. |
| 26 | |
| 27 | You should have received a copy of the GNU Affero General Public License along |
| 28 | with this program. If not, see <http://www.gnu.org/licenses/>. |
| 29 | |
| 30 | ## Prerequisites |
| 31 | |
| 32 | You need a working Android development environment, consisting of the Android |
| 33 | SKD and the Android NDK. The easiest way is to use Android Studio to download |
| 34 | and install the SDK and NDK. |
| 35 | |
| 36 | ## Building |
| 37 | |
| 38 | Download the project using Git: |
| 39 | |
| 40 | $ git clone git://git.ghostscript.com/mupdf-android-viewer.git |
| 41 | |
| 42 | Edit the local.properties file to point to your Android SDK directory: |
| 43 | |
| 44 | $ echo sdk.dir=$HOME/Android/Sdk > local.properties |
| 45 | |
| 46 | If all tools have been installed as per the prerequisites, build the app using |
| 47 | the gradle wrapper: |
| 48 | |
| 49 | $ ./gradlew assembleRelease |
| 50 | |
| 51 | If all has gone well, you can now find the app APKs in app/build/outputs/apk/, |
| 52 | with one APK for each ABI. There is also a universal APK which supports all |
| 53 | ABIs. |
| 54 | |
| 55 | The library component can be found in lib/build/outputs/aar/lib-release.aar. |
| 56 | |
| 57 | ## Running |
| 58 | |
| 59 | To run the app in the android emulator, first you'll need to set up an "Android |
| 60 | Virtual Device" for the emulator. Run "android avd" and create a new device. |
| 61 | You can also use Android Studio to set up a virtual device. Use the x86 ABI for |
| 62 | best emulator performance. |
| 63 | |
| 64 | Then launch the emulator, or connect a device with USB debugging enabled: |
| 65 | |
| 66 | $ emulator -avd MyVirtualDevice & |
| 67 | |
| 68 | Then copy some test files to the device: |
| 69 | |
| 70 | $ adb push file.pdf /mnt/sdcard/Download |
| 71 | |
| 72 | Then install the app on the device: |
| 73 | |
| 74 | $ ./gradlew installDebug |
| 75 | |
| 76 | To start the installed app on the device: |
| 77 | |
| 78 | $ adb shell am start -n com.artifex.mupdf.viewer.app/.LibraryActivity |
| 79 | |
| 80 | To see the error and debugging message log: |
| 81 | |
| 82 | $ adb logcat |
| 83 | |
| 84 | ## Building the JNI library locally |
| 85 | |
| 86 | The viewer library here is 100% pure java, but it uses the MuPDF fitz library, |
| 87 | which provides access to PDF rendering and other low level functionality. |
| 88 | The default is to use the JNI library artifact from the Ghostscript Maven |
| 89 | repository. |
| 90 | |
| 91 | If you want to build the JNI code yourself, you will need to check out the |
| 92 | 'jni' submodule recursively. You will also need a working host development |
| 93 | environment with a C compiler and GNU Make. |
| 94 | |
| 95 | Either clone the original project with the --recursive flag, or initialize all |
| 96 | the submodules recursively by hand: |
| 97 | |
| 98 | mupdf-mini $ git submodule update --init |
| 99 | mupdf-mini $ cd jni |
| 100 | mupdf-mini/jni $ git submodule update --init |
| 101 | mupdf-mini/jni $ cd libmupdf |
| 102 | mupdf-mini/jni/libmupdf $ git submodule update --init |
| 103 | |
| 104 | Then you need to run the 'make generate' step in the libmupdf directory: |
| 105 | |
| 106 | mupdf-mini/jni/libmupdf $ make generate |
| 107 | |
| 108 | Once this is done, the build system should pick up the local JNI library |
| 109 | instead of using the Maven artifact. |
| 110 | |
| 111 | ## Release |
| 112 | |
| 113 | To do a release you MUST first change the package name! |
| 114 | |
| 115 | Do NOT use the com.artifex domain for your custom app! |
| 116 | |
| 117 | In order to sign a release build, you will need to create a key and a key |
| 118 | store. |
| 119 | |
| 120 | $ keytool -genkey -v -keystore app/android.keystore -alias MyKey \ |
| 121 | -validity 3650 -keysize 2048 -keyalg RSA |
| 122 | |
| 123 | Then add the following entries to app/gradle.properties: |
| 124 | |
| 125 | release_storeFile=android.keystore |
| 126 | release_storePassword=<your keystore password> |
| 127 | release_keyAlias=MyKey |
| 128 | release_keyPassword=<your key password> |
| 129 | |
| 130 | If your keystore has been set up properly, you can now build a signed release. |
| 131 | |
| 132 | ## Maven |
| 133 | |
| 134 | The library component of this project can be packaged as a Maven artifact. |
| 135 | |
| 136 | The default is to create the Maven artifact in the 'MAVEN' directory. You can |
| 137 | copy thoes files to the distribution site manually, or you can change the |
| 138 | uploadArchives repository in build.gradle before running the uploadArchives |
| 139 | task. |
| 140 | |
| 141 | $ ./gradlew uploadArchives |
| 142 | |
| 143 | Good Luck! |