source: gs3-extensions/i-jetty/trunk/src/README.txt@ 23883

Greenstone3 Runtime on Android
==============================

This extension helps you set up and run Greenstone3 on your android device.

It relies on the environment variable ANDROID_SDK_HOME to determine
where Android's SDK lives on your file system (primarily to be able to
run 'adb' and 'dex').  If this is not set prior to running the scripts
this extension provides, it can be set explicitly in setup.bash/bat.

Having sourced the setup file the two main steps are:

  1) Install i-jetty

  2) Install Greenstone3 as a web-app 
     (converting any jar and class files to DEX format)

The first step typically only needs to be done once. The second step is
composed of three sub-steps, and may require the last two sub-steps to
be repeated if the Java code is changed.

Step 1
=======

First, install i-jetty on your Android device.  You can do this through
the Market, or else type:

  adb install i-jetty-2.2-signed.apk

Note: for your Android device to install applications using 'adb' you
need to have enabled it's application 'Development' mode (under
Settings->Application)


Step 2
======

Next put your Android device into USB disk mode, and set up the necessary files
to run Greenstone3 as a web-app under i-jetty.  The three sub-steps are:


Step 2.1
--------

Transfer the bulk of the <GSDL3SRCHOME>/web structure to the 
<SDCARD>/ijetty/webapps/greenstone3 with:


  WEBAPP-ROOT-TO-SDCARD.sh

This script skips any .svn files if present.  It also skips installing
'localsite' as this is rather large -- both in size and in terms of
the number of files invovled -- so copying is rather slow, and it is
probably not what you want anyway.


Step 2.2
--------

Convert the class files (includes those stored in jar files) into
classs.dex with:

  JAVA-TO-DEX.sh  

The finished file, which is also by this point zipped up, is left in
the 'lib' folder.


Step 2.3
--------

Copy classes.zip onto the Android's sd-card

  DEX-TO-SDCARD.sh  

This is the final step in getting Greenstone3 setup on an Andoird.
Switch off the USB disk mode on the Android device.  Note: it can take
a device minute or two "preparing" the sd-card.  This can be seen
on the notification view.  Alternativey, if you try to start i-jetty
before the card is ready, then i-jetty points this out, and offers you
a 'retry' button.


Step 3
======

Launch i-jetty from my apps area.  Then, within i-jetty, start the
server.  Once the "Jetty started" message appears, switch to your
web-browser application.  We've tested the built-in web browser, and
Mobile Firefox 4.


If the Java code to Greenstone3 is changed, then you need to repeat sub-steps
2.2 and 2.3



Caveats:
========

1. Due to difficulties in getting MG and MGPP working on android
   through the NDK, these are currently not supported.  Effectively,
   the Greenstone3 used needs to be one compiled *without* JNI
   support.


2. Due to a runtime (reflection) error, we had to modify xalan.jar.
   The modified version of this file is also in the 'jars' folder
   used in this extension.