Update docs for Android SDK.

author: Tor Andersson <tor.andersson@artifex.com> 2017-10-24 13:17:18 +0200
committer: Tor Andersson <tor.andersson@artifex.com> 2017-11-13 17:05:18 +0100
commit: 4c6226da837e279a64770dcd51d54e40caf54b6f (patch)
tree: f4d62b4f3a04a970da22fbdb2a57237d0547c0ed /docs
parent: cfe37ae813fff7113b19b7c7009fb880aa37a037 (diff)
download: mupdf-4c6226da837e279a64770dcd51d54e40caf54b6f.tar.xz
5 files changed, 343 insertions, 310 deletions
diff --git a/docs/android-build-library.html b/docs/android-build-library.html
deleted file mode 100644
index f8a0e1c7..00000000
--- a/docs/android-build-library.html
+++ /dev/null
@@ -1,111 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-<title>How to build the MuPDF library for Android</title>
-<link rel="stylesheet" href="style.css" type="text/css">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-</head>
-
-<body>
-
-<header>
-<h1>How to build the MuPDF library for Android</h1>
-</header>
-
-<nav>
-<a href="http://mupdf.com/index.html">About</a>
-<a href="http://mupdf.com/news.html">News</a>
-<a href="index.html">Documentation</a>
-<a href="http://mupdf.com/downloads/">Downloads</a>
-<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">Source</a>
-<a href="https://bugs.ghostscript.com/">Bugs</a>
-</nav>
-
-<article>
-
-<p>
-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.
-
-<p>
-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!
-
-<p>
-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.
-
-<h2>Setting up the MuPDF subproject</h2>
-
-<p>
-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:
-
-<pre>
-$ git submodule add git://git.ghostscript.com/mupdf.git libmupdf
-$ cd libmupdf
-$ git submodule update --init
-</pre>
-
-<p>
-You can also unpack a release tarball archive in your source directory.
-
-<p>
-We'll assume you name the mupdf project directory 'libmupdf'.
-
-<p>
-Use your host compiler to run the 'generate' step in the mupdf project:
-
-<pre>
-$ make -C libmupdf generate
-</pre>
-
-<h2>Adding the JNI library</h2>
-
-<p>
-Add an NDK-build step to your project, using the Android.mk file from mupdf.
-
-<p>
-Add an externalNativeBuild section in the android section in the
-build.gradle file:
-
-<pre>
-android {
-	externalNativeBuild {
-		ndkBuild.path 'libmupdf/platform/java/Android.mk'
-	}
-}
-</pre>
-
-<h2>Adding the Java library</h2>
-
-<p>
-You'll also need to include the Java classes that bind to the JNI library.
-
-<p>
-Add the 'libmupdf/platform/java/src' directory to the list of source
-directories in the build.gradle file:
-
-<pre>
-android {
-	sourceSets {
-		main {
-			java.srcDirs 'src/main/java', 'libmupdf/platform/java/src'
-		}
-	}
-}
-</pre>
-
-</article>
-
-<footer>
-<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a>
-Copyright &copy; 2006-2017 Artifex Software Inc.
-</footer>
-
-</body>
-</html>
diff --git a/docs/android-build-viewer.html b/docs/android-build-viewer.html
deleted file mode 100644
index c13f4ab8..00000000
--- a/docs/android-build-viewer.html
+++ /dev/null
@@ -1,186 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-<title>How to build the MuPDF viewer for Android</title>
-<link rel="stylesheet" href="style.css" type="text/css">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-</head>
-
-<body>
-
-<header>
-<h1>How to build the MuPDF viewer for Android</h1>
-</header>
-
-<nav>
-<a href="http://mupdf.com/index.html">About</a>
-<a href="http://mupdf.com/news.html">News</a>
-<a href="index.html">Documentation</a>
-<a href="http://mupdf.com/downloads/">Downloads</a>
-<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">Source</a>
-<a href="https://bugs.ghostscript.com/">Bugs</a>
-</nav>
-
-<article>
-
-<h2>Prerequisites</h2>
-
-<p>
-You need a working Android development environment, consisting of the Android
-SDK and the Android NDK. The easiest way is to use Android Studio to download
-and install the SDK and NDK. Make sure that the Android/Sdk/tools and
-Android/Sdk/ndk-bundle directories are on your path.
-
-<p>
-You also need Oracle's Java JDK (OpenJDK is not compatible with Android).
-You also need the Apache Ant build system.
-You also need Git, GNU Make, and a C compiler.
-
-<p>
-If everything is working, you should be able to run these commands
-from the command line:
-
-<blockquote>
-	Android SDK tools: android, emulator, adb and apksigner.<br>
-	Android NDK tools: ndk-build.<br>
-	Oracle Java JDK 8: java, javac and keytool.<br>
-	Git: git.<br>
-	GNU Make: make, or gmake.<br>
-	C compiler: cc, gcc, or clang.
-</blockquote>
-
-<h2>Building</h2>
-
-<p>
-Download the project using Git (and don't forget the --recursive flag):
-
-<pre>
-$ git clone --recursive git://git.ghostscript.com/mupdf-android-viewer-mini.git
-</pre>
-
-<p>
-If all tools have been installed as per the prerequisites, first use your
-host compiler to run the 'generate' step in the mupdf project:
-
-<pre>
-$ make -C libmupdf generate
-</pre>
-
-<p>The build the app using the gradle wrapper:
-
-<pre>
-$ ./gradlew assembleDebug
-</pre>
-
-<p>
-You may need to set ANDROID_HOME or add a local.properties configuration
-file to point to where you have installed the Android SDK.
-
-<h2>Running</h2>
-
-<p>
-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.
-
-<p>
-Then launch the emulator, or connect a device with USB debugging enabled:
-
-<pre>
-$ emulator -avd MyVirtualDevice &amp;
-</pre>
-
-<p>
-Then copy some test files to the device:
-
-<pre>
-$ adb push file.pdf /mnt/sdcard/Download
-</pre>
-
-<p>
-Then install the app on the device:
-
-<pre>
-$ ./gradlew installDebug
-</pre>
-
-<p>
-To see the error and debugging message log:
-
-<pre>
-$ adb logcat
-</pre>
-
-<h2>Release</h2>
-
-<p>
-To release you <b>MUST</b> first change the package name.
-Do <b>NOT</b> use the com.artifex domain for your custom app!
-
-<p>
-Change all references to com.artifex.mupdf.mini into
-com.YourCompanyName.mupdf.mini in the Java source files and XML resources.
-
-<pre>
-$ git mv src/com/artifex src/com/YourCompanyName
-$ sed -i -e s,artifex,YourCompanyName,g AndroidManifest.xml
-$ sed -i -e "s,package com.artifex,package com.YourCompanyName,g" src/com/YourCompanyName/mupdf/mini/*.java
-$ sed -i -e s,artifex,YourCompanyName,g res/layout/*.xml
-</pre>
-
-<p>
-In order to sign a release build, you will need to create a key and a key store.
-
-<pre>
-$ keytool -genkey -v -keystore android.keystore -alias MyKey -validity 3650 -keysize 2048 -keyalg RSA
-</pre>
-
-<p>
-Then add the following entries to gradle.properties:
-
-<pre>
-RELEASE_KEY_STORE=android.keystore
-RELEASE_KEY_STORE_PASSWORD=<i>your keystore password</i>
-RELEASE_KEY_ALIAS=MyKey
-RELEASE_KEY_ALIAS_PASSWORD=<i>your key password</i>
-</pre>
-
-<p>
-If your keystore has been set up properly, you can now build a release APK.
-
-<pre>
-$ ./gradlew assembleRelease
-</pre>
-
-<p>
-First verify that the release APK has indeed been signed by the correct key.
-
-<pre>
-apksigner verify --print-certs ./build/outputs/apk/mupdf-x86-debug.apk
-apksigner verify --print-certs ./build/outputs/apk/mupdf-x86-release.apk
-</pre>
-
-<p>
-The debug APK should be signed by <i>Android Debug</i> while the release APK
-ought to be signed with the key you created above.
-
-<p>
-Finally install the release app on the device:
-
-<pre>
-$ ./gradlew installRelease
-</pre>
-
-<p>
-Good Luck!
-
-</article>
-
-<footer>
-<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a>
-Copyright &copy; 2006-2017 Artifex Software Inc.
-</footer>
-
-</body>
-</html>
diff --git a/docs/android-sdk.html b/docs/android-sdk.html
new file mode 100644
index 00000000..d48a33af
--- /dev/null
+++ b/docs/android-sdk.html
@@ -0,0 +1,330 @@
+<!DOCTYPE html>
+<html>
+<head>
+<title>MuPDF Android SDK</title>
+<link rel="stylesheet" href="style.css" type="text/css">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<style>
+body {counter-reset: h2}
+h2 {counter-reset: h3}
+h3 {counter-reset: h4}
+h4 {counter-reset: h5}
+h5 {counter-reset: h6}
+h2:before {counter-increment: h2; content: counter(h2) ". "}
+h3:before {counter-increment: h3; content: counter(h2) "." counter(h3) ". "}
+h4:before {counter-increment: h4; content: counter(h2) "." counter(h3) "." counter(h4) ". "}
+h5:before {counter-increment: h5; content: counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) ". "}
+h6:before {counter-increment: h6; content: counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) "." counter(h6) ". "}
+</style>
+</head>
+
+<body>
+
+<header>
+<h1>MuPDF Android SDK</h1>
+</header>
+
+<nav>
+<a href="http://mupdf.com/index.html">About</a>
+<a href="http://mupdf.com/news.html">News</a>
+<a href="index.html">Documentation</a>
+<a href="http://mupdf.com/downloads/">Downloads</a>
+<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">Source</a>
+<a href="https://bugs.ghostscript.com/">Bugs</a>
+</nav>
+
+<article>
+
+<p>
+This document outlines the steps necessary to use the MuPDF Android SDK in various ways.
+
+<p>
+First, we show you how to embed the SDK in your app. Then, we explain how to
+customize the viewer if you need to change how it looks or behaves. Finally, we
+tell you where to go if you need to do work on the SDK itself.
+
+<p>
+Embedding the viewer in your app provides an activity that you can start to
+view PDF documents from within your app. This should be enough for most use
+cases.
+
+<h2 id="acquire-license">
+Acquire a valid license
+</h2>
+
+<p>
+Before using MuPDF, please make sure that you have a valid license to do so.
+There are two available licenses; make sure you pick the one whose terms you can comply with.
+
+<h3>
+Open Source license
+</h3>
+
+<p>
+If your software is open source, you may use MuPDF under the terms of the
+<a href="https://www.gnu.org/licenses/agpl-3.0.html">GNU Affero General Public License</a>.
+
+<p>
+This means that <i>all of the source code</i> for your <i>complete</i> app must be
+released under a compatible open source license!
+
+<p>
+It also means that you may <i>not</i> use any proprietary closed source libraries or
+components in your app. This includes (but is not limited to)
+	Google Play Services,
+	Google Mobile Services,
+	AdMob by Google,
+	Crashlytics,
+	Answers,
+	etc.
+
+<p>
+Just because a library ships with Android or is made by Google does <i>not</i> make it AGPL compatible!
+
+
+<p>
+If you cannot or do not want to comply with these restrictions,
+you <i><b>must</b></i> acquire a commercial license instead.
+
+<h3>
+Commercial license
+</h3>
+
+<p>
+If your software is not open source, Artifex Software can sell you a license to use MuPDF in closed source software.
+Go and fill out the <a href="http://artifex.com/contact-us/">product inquiry form</a>
+for commercial licensing terms and pricing.
+
+<h2 id="setup-build">
+Add the MuPDF SDK to your project
+</h2>
+
+<p>
+The MuPDF library uses the Gradle build system.
+In order to include MuPDF in your app, you also need to use Gradle.
+The Eclipse and Ant build systems are not supported.
+
+<p>
+The MuPDF library needs Android version 4.1 or newer.
+Make sure that the minSdkVersion in your app's build.gradle is at least 16.
+
+<pre>
+android {
+	defaultConfig {
+		<b>minSdkVersion 16</b>
+		...
+	}
+	...
+}
+</pre>
+
+<p>
+The MuPDF library can be retrieved as a pre-built artifact from our Maven repository.
+Add the maven repository to your project. In your project's top build.gradle, add the bolded line to
+to the repositories section:
+
+<pre>
+allprojects {
+	repositories {
+		jcenter()
+		<b>maven { url 'http://maven.ghostscript.com' }</b>
+		...
+	}
+}
+</pre>
+
+<p>
+Then add the MuPDF viewer library to your app's dependencies.
+In your app's build.gradle, add the bolded line to the dependencies section:
+
+<pre>
+dependencies {
+	<b>compile 'com.artifex.mupdf:viewer:1.11.+'</b>
+	...
+}
+</pre>
+
+<h2 id="use-activity">
+Invoke the document viewer activity
+</h2>
+
+<p>
+Once this has been done, you have access to the MuPDF viewer activity.
+You can now open a document viewing activity by launching an intent,
+passing the URI of the document you wish to view.
+
+<pre>
+import com.artifex.mupdf.viewer.DocumentActivity;
+
+public void startMuPDFActivity(Uri documentUri) {
+	Intent intent = new Intent(this, DocumentActivity.class);
+	intent.setAction(Intent.ACTION_VIEW);
+	intent.setData(documentUri);
+	startActivity(intent);
+}
+</pre>
+
+<p>
+The activity supports viewing both file and content scheme URIs.
+
+<p>
+For example, to open the PDF file in ~/Download/example.pdf:
+
+<pre>
+public void startMuPDFActivityWithExampleFile() {
+	File dir = Environment.getExternalStoragePublicDirectory
+		(Environment.DIRECTORY_DOWNLOADS);
+	File file = new File(dir, "example.pdf")
+	Uri uri = Uri.fromFile(file);
+	startMuPDFActivity(uri);
+}
+</pre>
+
+<h2>
+How to customize the viewer
+</h2>
+
+<p>
+If you've already tried embedding the viewer in your app, but are unhappy with some
+aspect of the look or behavior and want to modify it in some way, this document should
+point you in the right direction.
+
+<h3>
+Decide which viewer to base your customizations on
+</h3>
+
+<p>
+In order to customize the viewer UI, you will need to modify the existing android viewer activity.
+There are two separate code bases you can start with:
+
+<dl>
+<dt>mupdf-android-viewer:
+<dd>The main viewer app. This code is difficult to work with, but has the most
+features and pre-renders neighboring pages into a page cache for faster page
+turning performance.
+<dt>mupdf-android-viewer-mini:
+<dd>This is a minimalist viewer which has fewer features but is designed to be
+easy to understand and modify. It does not (currently) have high-resolution
+zooming, and it does not use the swipe gesture to flip pages (it requires the
+user to tap on the side of the screen to flip pages).
+</dl>
+
+<p>
+If all you want to do is brand the UI with your own colors and icons, you are
+welcome to use whichever code base you prefer. However, if you want to do
+extensive modifications, we suggest you base your code on the mini viewer.
+
+<h3>
+Check out the chosen project
+</h3>
+
+<p>
+When you have decided which project to base your modifications on, you should check out
+the corresponding git repository:
+
+<pre>
+$ git clone git://git.ghostscript.com/mupdf-android-viewer.git
+$ git clone git://git.ghostscript.com/mupdf-android-viewer-mini.git
+</pre>
+
+<p>
+Inside the checked out project you will find two modules: app and lib.
+The app module is a file chooser activity that lets the user open files from the external storage.
+The lib module is the viewer activity, which provides the "com.artifex.mupdf:viewer"
+package that you're already using.
+
+<p>
+The lib module is the one you want; ignore everything else in this project.
+
+<h3>
+Copy the viewer library module into your project
+</h3>
+
+<p>
+Copy the 'lib' directory to your project, renaming it to something appropriate.
+The following instructions assume you called the directory 'mupdf-lib'.
+Don't forget to include the module in the settings.gradle file:
+
+<pre>
+include ':app'
+<b>include ':mupdf-lib'</b>
+...
+</pre>
+
+<p>
+You'll also want to change your app's dependencies to now depend on your local
+copy rather than the official mupdf viewer package. In your app build.gradle:
+
+<pre>
+dependencies {
+	<strike>compile 'com.artifex.mupdf:viewer:1.11.+'</strike>
+	<b>compile project(':mupdf-lib')</b>
+	...
+}
+</pre>
+
+<p>
+The lib module depends on the JNI library "com.artifex.mupdf:fitz", so do
+<i>not</i> remove the maven repository from your top build.gradle.
+
+<h3>
+Edit the viewer activity
+</h3>
+
+<p>
+If all has gone well, you can now build your project with the local viewer library,
+and access the mupdf viewer activity just as you used to.
+
+<p>
+You're now free to customize the resources in mupdf-lib/src/main/res and behavior in
+mupdf-lib/src/main/java as you desire.
+
+<h2>
+Working on the MuPDF SDK
+</h2>
+
+<p>
+If you want to work on the SDK itself, rather than just use it, you will need
+to check out the following git repositories.
+
+<dl>
+<dt>mupdf.git
+<dd>This repository contains the low-level "fitz" C library and the JNI bindings.
+<dt>mupdf-android-fitz.git
+<dd>This repository contains an Android project to build the C library and JNI bindings.
+It uses mupdf.git as a git submodule.
+<dt>mupdf-android-viewer.git
+<dd>This repository contains the Android viewer library and app.
+It uses mupdf-android-fitz.git as either a Maven artifact or git submodule.
+<dt>mupdf-android-viewer-mini.git
+<dd>This repository contains the minimalist Android viewer library and app.
+It uses mupdf-android-fitz.git as either a Maven artifact or git submodule.
+<dt>mupdf-android-viewer-old.git
+<dd>This repository contains the old Android viewer. It has its own JNI
+bindings and uses mupdf.git as a submodule directly. It is only listed here for
+completeness sake, and is not part of the SDK.
+</dl>
+
+<p>
+Since these repositories are set up as git submodules, if you're a Git expert,
+you can clone one of the viewer repositories recursively and get all of them at
+once. However, working with git submodules can be fraught with danger, so it
+may be easier to check them out individually.
+
+<p>
+If you only want to work with one of the viewer repositories, you can use the
+Maven artifact for the JNI bindings library and not worry about the mupdf.git
+and mupdf-android-fitz.git repositories.
+
+<p>
+Good luck!
+
+</article>
+
+<footer>
+<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a>
+Copyright &copy; 2006-2017 Artifex Software Inc.
+</footer>
+
+</body>
+</html>
diff --git a/docs/index.html b/docs/index.html
index afcff2e8..59a11a5b 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -44,12 +44,12 @@ Read the <a href="manual-mupdf-gl.html">manual for the new Linux and Windows vie
 Android currently has several different viewers with varying degrees of complexity:
 
 <dl>
-<dt><a href="https://play.google.com/store/apps/details?id=com.artifex.mupdf.mini">MuPDF mini</a>
-<dd>A minimal code example of a document viewer.
-<dt><a href="https://play.google.com/store/apps/details?id=com.artifex.mupdfdemo">MuPDF demo</a>
+<dt><a href="https://play.google.com/store/apps/details?id=com.artifex.mupdfdemo">MuPDF</a>
 <dd>The main app on Google Play. Supports forms and annotations.
-<dt>MuPDF NUI
-<dd>A viewer that matches the look &amp; feel of SmartOffice. This product is still in early development.
+<dt><a href="https://play.google.com/store/apps/details?id=com.artifex.mupdf.viewer.app">MuPDF viewer</a>
+<dd>A slimmed down viewer only variant of the main app.
+<dt><a href="https://play.google.com/store/apps/details?id=com.artifex.mupdf.mini.app">MuPDF mini</a>
+<dd>A minimal code example of a document viewer.
 </dl>
 
 <p>
@@ -120,15 +120,15 @@ The book is also available as a <a href="book.pdf">PDF</a> and <a href="book.epu
 There is also a Java library, which uses JNI to provide access to the C library.
 The Java classes provide an interface very similar to that available in the
 <a href="manual-mutool-run.html">mutool run</a> command line tool.
-This Java library is also how you use MuPDF on Android.
+This Java library also powers the Android SDK.
 
 <p>
-If you want to build an application for Android, you have several options. You can base it off one of
-the existing viewers, or build a new app using the Java library directly.
+If you want to build an application for Android, you have several options. You
+can base it off one of the existing viewers, or build a new app using the Java
+library directly.
 
 <ul>
-<li><a href="android-build-viewer.html">How to build the Android viewer</a>.
-<li><a href="android-build-library.html">How to build the Android library</a>.
+<li><a href="android-sdk.html">Android SDK documentation</a>.
 </ul>
 
 <h2>Contributing</h2>
diff --git a/docs/manual-mupdf-gl.html b/docs/manual-mupdf-gl.html
index 514c737a..ffd2b7ce 100644
--- a/docs/manual-mupdf-gl.html
+++ b/docs/manual-mupdf-gl.html
@@ -24,9 +24,9 @@
 <article>
 
 <p>
-The OpenGL based viewer can read PDF, XPS, CBZ, and EPUB documents.
-It compiles on any platform that <a href="http://glfw.org/">GLFW</a> supports.
-The latest release builds on Linux, Windows, and macOS.
+The OpenGL based viewer can read PDF, XPS, CBZ, EPUB, and FB2 documents.
+It compiles on any platform that has a <a href="http://freeglut.sourceforge.net/">GLUT</a> library.
+The latest release builds on Linux, Windows, and MacOS.
 
 <h2>Command Line Options</h2>
author	Tor Andersson <tor.andersson@artifex.com>	2017-10-24 13:17:18 +0200
committer	Tor Andersson <tor.andersson@artifex.com>	2017-11-13 17:05:18 +0100
commit	4c6226da837e279a64770dcd51d54e40caf54b6f (patch)
tree	f4d62b4f3a04a970da22fbdb2a57237d0547c0ed /docs
parent	cfe37ae813fff7113b19b7c7009fb880aa37a037 (diff)
download	mupdf-4c6226da837e279a64770dcd51d54e40caf54b6f.tar.xz