From 4c6226da837e279a64770dcd51d54e40caf54b6f Mon Sep 17 00:00:00 2001 From: Tor Andersson Date: Tue, 24 Oct 2017 13:17:18 +0200 Subject: Update docs for Android SDK. --- docs/android-build-library.html | 111 -------------- docs/android-build-viewer.html | 186 ---------------------- docs/android-sdk.html | 330 ++++++++++++++++++++++++++++++++++++++++ docs/index.html | 20 +-- docs/manual-mupdf-gl.html | 6 +- 5 files changed, 343 insertions(+), 310 deletions(-) delete mode 100644 docs/android-build-library.html delete mode 100644 docs/android-build-viewer.html create mode 100644 docs/android-sdk.html 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 @@ - - - -How to build the MuPDF library for Android - - - - - - -
-

How to build the MuPDF 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: - -

-$ git submodule add git://git.ghostscript.com/mupdf.git libmupdf
-$ cd libmupdf
-$ git submodule update --init
-
- -

-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: - -

-$ make -C libmupdf generate
-
- -

Adding the JNI library

- -

-Add an NDK-build step to your project, using the Android.mk file from mupdf. - -

-Add an externalNativeBuild section in the android section in the -build.gradle file: - -

-android {
-	externalNativeBuild {
-		ndkBuild.path 'libmupdf/platform/java/Android.mk'
-	}
-}
-
- -

Adding the Java library

- -

-You'll also need to include the Java classes that bind to the JNI library. - -

-Add the 'libmupdf/platform/java/src' directory to the list of source -directories in the build.gradle file: - -

-android {
-	sourceSets {
-		main {
-			java.srcDirs 'src/main/java', 'libmupdf/platform/java/src'
-		}
-	}
-}
-
- -
- - - - - 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 @@ - - - -How to build the MuPDF viewer for Android - - - - - - -
-

How to build the MuPDF viewer for Android

-
- - - -
- -

Prerequisites

- -

-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. - -

-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. - -

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

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

Building

- -

-Download the project using Git (and don't forget the --recursive flag): - -

-$ git clone --recursive git://git.ghostscript.com/mupdf-android-viewer-mini.git
-
- -

-If all tools have been installed as per the prerequisites, first use your -host compiler to run the 'generate' step in the mupdf project: - -

-$ make -C libmupdf generate
-
- -

The build the app using the gradle wrapper: - -

-$ ./gradlew assembleDebug
-
- -

-You may need to set ANDROID_HOME or add a local.properties configuration -file to point to where you have installed the Android SDK. - -

Running

- -

-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: - -

-$ emulator -avd MyVirtualDevice &
-
- -

-Then copy some test files to the device: - -

-$ adb push file.pdf /mnt/sdcard/Download
-
- -

-Then install the app on the device: - -

-$ ./gradlew installDebug
-
- -

-To see the error and debugging message log: - -

-$ adb logcat
-
- -

Release

- -

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

-Change all references to com.artifex.mupdf.mini into -com.YourCompanyName.mupdf.mini in the Java source files and XML resources. - -

-$ 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
-
- -

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

-$ keytool -genkey -v -keystore android.keystore -alias MyKey -validity 3650 -keysize 2048 -keyalg RSA
-
- -

-Then add the following entries to gradle.properties: - -

-RELEASE_KEY_STORE=android.keystore
-RELEASE_KEY_STORE_PASSWORD=your keystore password
-RELEASE_KEY_ALIAS=MyKey
-RELEASE_KEY_ALIAS_PASSWORD=your key password
-
- -

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

-$ ./gradlew assembleRelease
-
- -

-First verify that the release APK has indeed been signed by the correct key. - -

-apksigner verify --print-certs ./build/outputs/apk/mupdf-x86-debug.apk
-apksigner verify --print-certs ./build/outputs/apk/mupdf-x86-release.apk
-
- -

-The debug APK should be signed by Android Debug while the release APK -ought to be signed with the key you created above. - -

-Finally install the release app on the device: - -

-$ ./gradlew installRelease
-
- -

-Good Luck! - -

- - - - - 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 @@ + + + +MuPDF Android SDK + + + + + + + +
+

MuPDF Android SDK

+
+ + + +
+ +

+This document outlines the steps necessary to use the MuPDF Android SDK in various ways. + +

+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. + +

+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. + +

+Acquire a valid license +

+ +

+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. + +

+Open Source license +

+ +

+If your software is open source, you may use MuPDF under the terms of the +GNU Affero General Public License. + +

+This means that all of the source code for your complete app must be +released under a compatible open source license! + +

+It also means that you may not 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. + +

+Just because a library ships with Android or is made by Google does not make it AGPL compatible! + + +

+If you cannot or do not want to comply with these restrictions, +you must acquire a commercial license instead. + +

+Commercial license +

+ +

+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 product inquiry form +for commercial licensing terms and pricing. + +

+Add the MuPDF SDK to your project +

+ +

+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. + +

+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. + +

+android {
+	defaultConfig {
+		minSdkVersion 16
+		...
+	}
+	...
+}
+
+ +

+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: + +

+allprojects {
+	repositories {
+		jcenter()
+		maven { url 'http://maven.ghostscript.com' }
+		...
+	}
+}
+
+ +

+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: + +

+dependencies {
+	compile 'com.artifex.mupdf:viewer:1.11.+'
+	...
+}
+
+ +

+Invoke the document viewer activity +

+ +

+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. + +

+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);
+}
+
+ +

+The activity supports viewing both file and content scheme URIs. + +

+For example, to open the PDF file in ~/Download/example.pdf: + +

+public void startMuPDFActivityWithExampleFile() {
+	File dir = Environment.getExternalStoragePublicDirectory
+		(Environment.DIRECTORY_DOWNLOADS);
+	File file = new File(dir, "example.pdf")
+	Uri uri = Uri.fromFile(file);
+	startMuPDFActivity(uri);
+}
+
+ +

+How to customize the viewer +

+ +

+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. + +

+Decide which viewer to base your customizations on +

+ +

+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: + +

+
mupdf-android-viewer: +
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. +
mupdf-android-viewer-mini: +
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). +
+ +

+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. + +

+Check out the chosen project +

+ +

+When you have decided which project to base your modifications on, you should check out +the corresponding git repository: + +

+$ git clone git://git.ghostscript.com/mupdf-android-viewer.git
+$ git clone git://git.ghostscript.com/mupdf-android-viewer-mini.git
+
+ +

+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. + +

+The lib module is the one you want; ignore everything else in this project. + +

+Copy the viewer library module into your project +

+ +

+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: + +

+include ':app'
+include ':mupdf-lib'
+...
+
+ +

+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: + +

+dependencies {
+	compile 'com.artifex.mupdf:viewer:1.11.+'
+	compile project(':mupdf-lib')
+	...
+}
+
+ +

+The lib module depends on the JNI library "com.artifex.mupdf:fitz", so do +not remove the maven repository from your top build.gradle. + +

+Edit the viewer activity +

+ +

+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. + +

+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. + +

+Working on the MuPDF SDK +

+ +

+If you want to work on the SDK itself, rather than just use it, you will need +to check out the following git repositories. + +

+
mupdf.git +
This repository contains the low-level "fitz" C library and the JNI bindings. +
mupdf-android-fitz.git +
This repository contains an Android project to build the C library and JNI bindings. +It uses mupdf.git as a git submodule. +
mupdf-android-viewer.git +
This repository contains the Android viewer library and app. +It uses mupdf-android-fitz.git as either a Maven artifact or git submodule. +
mupdf-android-viewer-mini.git +
This repository contains the minimalist Android viewer library and app. +It uses mupdf-android-fitz.git as either a Maven artifact or git submodule. +
mupdf-android-viewer-old.git +
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. +
+ +

+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. + +

+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. + +

+Good luck! + +

+ + + + + 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 manual for the new Linux and Windows vie Android currently has several different viewers with varying degrees of complexity:
-
MuPDF mini -
A minimal code example of a document viewer. -
MuPDF demo +
MuPDF
The main app on Google Play. Supports forms and annotations. -
MuPDF NUI -
A viewer that matches the look & feel of SmartOffice. This product is still in early development. +
MuPDF viewer +
A slimmed down viewer only variant of the main app. +
MuPDF mini +
A minimal code example of a document viewer.

@@ -120,15 +120,15 @@ The book is also available as a PDF and mutool run command line tool. -This Java library is also how you use MuPDF on Android. +This Java library also powers the Android SDK.

-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.

Contributing

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 @@

-The OpenGL based viewer can read PDF, XPS, CBZ, and EPUB documents. -It compiles on any platform that GLFW 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 GLUT library. +The latest release builds on Linux, Windows, and MacOS.

Command Line Options

-- cgit v1.2.3