Adobe RMSDK and DL Reader

Building RMSDK and DL Reader on Android, using Eclipse

Requirements

The instructions apply to DL Reader for Android v4.1.x for use with RMSDK 11.0.2, released January 12, 2015.

Note:To write software for an eReader viewer app with RMSDK for use on Android devices, you need to use Mac hardware.

The following are recommended for building DL Reader for Android:

  • For your Mac computer we recommend the Mac OS 10.9.5 or Mac Yosemite (OS 10.10.3) as the minimum version of your operating system.
  • Java Standard Edition Development Kit (JDK) 1.6.0
  • Apache Ant 1.9.4
  • ADT Plugin for Eclipse (Indigo or greater)
  • Android 2.2, API level 8 SDK (via Android SDK Manager)
  • Android NDK r9d and GCC 4.8 for the DL Reader JNI. NDK r9d for Mac is available here.
  • OpenSSL version 1.0.1j. The same web page also provides source code distribution for earlier versions of the software.
  • cURL version 7.36.0. You can download the curl-7.36.0.tar.gz file directly, or visit the download page to access earlier versions of the software. Click the Old Releases option in the Related box on the right side of the screen.

DL Reader files

DLReader for Android builds against an RMSDK binary. Beginning with RMSDK 11, DL Reader does not build RMSDK from source.

Unzip your source distribution file for DL Reader into the samples sub-directory of your RMSDK 11 installation folder, so that your DL Reader project will be stored there.

For example:
$ cd ~/Adobe_RMSDK_11/samples
$ unzip ~/Downloads/DLReader-Android-4.1.3.zip
Your DL Reader installation is now found at:
~/Adobe_RMSDK_11/samples/DLReader-Android-4.1.3/
Look for the rmsdk-exports sub-directory in your DL Reader installation folder. This directory contains two files that must be copied into the RMSDK folder structure.

  1. DLBuildAndroidExternals.mak. Copy this file to the root directory for the RMSDK installation package.
  2. Makefile. Copy this also to the RMSDK root directory.

For example:
$ cd ~/Adobe_RMSDK_11
$ cp samples/DLReader-Android-4.1.3/rmsdk-exports/Makefile

RMSDK resources directory

The RMSDK resources directory is where the fonts, hyphen dictionaries, and certificates are stored.

For each build target, the RMSDK resources directory can be found at the following path, substituting the target name for the string [target]:
apps/[target]/assets/rmsdk
So the directory might look like this:
apps/dlreaderalpha/assets/rmsdk

Configure environment variables

In order to build dp and DL Reader from the command line, you will need to add directories to your environment PATH.

  • ANDROID_NDK. Path to where you unzipped the Android NDK files.
  • ANDROID_SDK. Path to your Android SDKs. In Eclipse, select Preferences Eclipsepreferencese and then Android and SDK Location.
  • ANT_PATH. Path to your Apache Ant bin folder.

For your convenience, dlreader-seten.sh is provided in the root of your DL Reader distribution.

Open the file in an editor:

dlreadersetenshfile1

Remove the comments for two lines, for Android NDK and Android SDK:

dlreadersetenshfile2

Set their values appropriately. Modify your PATH with the following command:

$ . dlreader-setenv.sh

Make sure that you run this shell script with the initial period (“$ . “) followed by a space.

Build external libraries

Build OpenSSL and cURL from source files before you build DL Reader. The recommended files are listed at the beginning of this page.

Datalogics provides a makefile (DLBuildAndroidExternals.mak) for building these libraries. Make sure that you have copied it to the right RMSDK directory.

  1. Unpack OpenSSL into your RMSDK root directory. Rename the directory to openssl.
  2. Unpack Curl into your RMSDK root directory. Rename the directory to curl
  3. From your RMSDK root, run:

make -f DLBuildAndroidExternals.mak
After the build is complete, the static libraries will be placed in these directories:

  • thirdparty/openssl/public/linux_arm_android-ndk
  • thirdparty/curl/public/linux_arm_android-ndk

Build dp module

The dp library is an RMSDK module that is shared in source code format to support reader-specific implementations of RMSDK device interfaces. This library must be built from source code.

Datalogics has created a makefile for quickly building the dp library on iOS and Android platforms. Make sure that you have copied the makefile to the right RMSDK directory.

Run this command from the root directory of RMSDK:
make <target>
The command can have one of these three forms. This one builds the dp library in debug mode:
make dp-android-debug
This builds the dp library in release mode:
make dp-android-release
This builds both of the above targets:
make dp-android-all
The static library and/or libraries will be copied to the appropriate folders per configuration in:
lib/android/<configuration>armeabi-v7a

Configure your development certificate

Starting with RMSDK 11, all applications built using RMSDK require a certificate file from Adobe Systems to allow you to distribute your code. Without a valid certificate, RMSDK APIs will not work properly.

There are two types of certificates, development and distribution. The development certificate is for building a new application, and can be used on multiple projects and platforms, but it expires after 60 days. When your development certificate expires, you need to submit a new form to replace it. You will need a distribution certificate when you plan to release an eReader app to market. Distribution certificates do not expire, and are good for each build of an application. But you must request a new distribution certificate whenever you change the source code for your app, or release a new build for the product.

To learn more about distribution certificates, see the files included in RMSDK11_Signing_Certificate_Info_v2.zip, provided with the RMSDK deliverables. You can download this zip file from an FTP site provided by Datalogics after you purchase the product.

Request both types of certificates from Datalogics. See the Adobe Systems Development Certificate. Look at ReadMe1st_DL.txt in RMSDK_CERTIFICATION_v3.zip for details on how to place your request.

After you receive the Adobe development certificate from Datalogics you need to configure DL Reader to find it. The certificate comes in the form of a file called ReaderClientCert.sig.

  1. Store the ReaderClientCert.sig file wherever you like.
  2. Look in your DL Reader directory. Find and open rmsdk_cert.cfg from the build/android folder.
  3. Change the cert-path value to point to where you copied the ReaderClientCert.sig file. It will default to DropBox. The cert-path parameter references the folder where the ReaderClientCert.sig file is stored.

For example, edit the rmsdk_cert.cfg file to look like this:

[CertificateLocation]
cert-path=~/resources
Note:Do not change the name of the certificate file ReaderClientCert.sig.

Build a DL Reader debug release from the command line

In your DL Reader Android root directory, complete these steps:

  1. Run the command ./update-project.sh
  2. Go to the directory build/android
  3. Run the command make debug-release Target=DLReader

These steps will create two files, the Android Application Package:

build/android/bin/DLReader-debug.apk

And the DL Reader Shared Object file:

build/android/obj/local/armeabi-v7a/libdlreader-jni.so

Building DL Reader targets

Datalogics offers three three target builds for RMSDK:

  • DL Reader
  • DL Reader Alpha
  • DL Reader Beta

All of these builds rely on the DL Reader Library project, and can be built from either the command line or from Eclipse.

Building DL Reader from a command line

  1. Run the command

./update-project.sh

  1. Move to the build/android directory.
  2. Run:

make <configuration> TARGET=<target build> RMSDK_VERSION=<rmsdk version>

Where configuration is one of the following:

Configuration value Description
debug Build DL Reader code in debug and link with a debug RMSDK
debug-release Build DL Reader java code in debug–DL Reader native code in release and link with a release RMSDK
release-build DL Reader code in release and link with a release RMSDK
headers Generate DL Reader JNI headers. This target is executed as part of one of the following:
make
make debug
make debug-release
make release
clean Remove build products
version Change the version number in DL Reader using a script that runs "git describe"
version-clean Checkout the original version of res/value/config.xml from the git repository
distribution Build DL Reader without copying the RMSDK development certificate into the APK

The target build is one of these values:

  • DLReader
  • DLReaderAlpha
  • DLReaderBeta

The rmsdk version is optional, but can be one of these values:

  • 1000 – RMSDK 10
  • 1100 – RMSDK 11 (default)

The make command will put an .apk file in the build/android/bin directory which can be installed to test the app. The command might look like this:

make <clean> TARGET=<DLReader>

Note:You must build DL Reader from the command line at least once before you build DL Reader using Eclipse. This is needed to create the C++ native library file libdlreader-jni.so.

Building DL Reader in Eclipse

  1. Open Eclipse.
  2. Create a new workspace:
    1. In Eclipse, select File, then Switch Workspace and then Other.
    2. Select a path for your new workspace.
    3. Click OK. Eclipse will restart, and create your new workspace.
  3. Import the android-viewer project into your workspace:
    1. In Eclipse, click File and Import.
    2. Then, select Android and Existing Android Code Into Workspace. Click Next.
    3. In the Root Directory field on the Import dialog, select the path to DL Reader Android.
    4. Confirm that several projects appear under Project to Import. Click Finish.
    5. Under the Package Explorer, you will see the target builds, DL Reader, DL Reader Alpha, and DL Reader Beta, along with some third party items like tree-view and shelves.
  4. Eclipse will build the workspace automatically.
  5. Run DL Reader.
    1. Connect an Android device with debugging enabled, or launch an Android Virtual Device.
    2. Under Package Explorer, select DL Reader, and then select Run/Debug As. Select Android Application.
    3. Alternately, you can select the DL Reader target and select Run and Run Configurations.
    4. Within the Run Configurations dialog, on the Android tab, select Launch Default Activity, and then click Browse to select a target for the Project. Also enter a name for the new configuration, “DL Reader.”
    5. Then, on the Target tab, select “Always prompt to pick device.” Then, scroll to the bottom of the window, and find the Additional Emulator Command Line Options field. Enter “-partition-size 1024” and click Run.

Dictionary support

DL Reader for Android offers the ability to use the Merriam Webster dictionary web service to look up the definition of a word on a page in an ebook file. This feature is turned off by default in DL Reader source code that Datalogics distributes to its customers.

To enable the dictionary feature in DL Reader, you need to register the Merriam Webster web page, to create an account, and select the type of dictionary you want to use.

This service is optional, though recommended. Note that you must pay for this dictionary service from Merriam Webster.

Options include:

  • Collegiate Dictionary
  • Collegiate Thesaurus
  • Spanish-English Dictionary
  • Medical Dictionary
  • Elementary Dictionary
  • Intermediate Dictionary
  • School Dictionary
  • Learners Dictionary

You may only select one dictionary.

After you have signed up, you will be given a URL to the web service for the dictionary you selected, and a key to access the dictionary.

You need to edit an XML file found in the DL Reader directory that you copied to RMSDK/Samples to add the URL and key:

customer-dictionary-config.xml

Replace the text shown, online_dictionary_url and online_dictionary_key:

Dictionary

After you enter these values in customer-dictionary-config.xml, copy the file to this directory:

build/android/res/values/

This way, when you build your RMSDK application this file will be copied into that application. If you don’t edit this XML config file to add the URL and key, the “define” option will not be displayed when a user selects text while reading an ebook in DL Reader. After you copy the file and rebuild your application, the next time you select text in DL Reader for Android the “define” option should appear. When you tap a word, it will query the dictionary web service and display a definition.

If you do not use DL Reader source code as the base of your application, you can still use the dictionary service, but you also need to make sure that the  DictionaryLibrary.jar file is included in your application. This file is stored in the DL Reader directory you copied under RMSDK/Samples, in build/android/libs.

Installing the Findbugs plugin for Eclipse

Findbugs is an Eclipse plugin that uses static analysis to find bugs in Java code. Available for free from the Eclipse Marketplace, Findbugs is widely used by Java developers. We recommend that you install Findbugs, as this software will make it fast and easy to identify problems in the code you create for any app you seek to build with RMSDK.

This plugin is optional.

  1. Open Eclipse, and select Help and Eclipse Marketplace.
  2. Search for Findbugs, and then install the plugin when it appears. You will need to restart Eclipse when the process is complete.
  3. Findbugs has its own perspective in Eclipse. Select Window, Perspective, and Open Perspective.

To learn more, view the description of the Findbugs plugin on the Eclipse Marketplace web page.