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