[23883] | 1 |
|
---|
| 2 | Greenstone3 Runtime on Android
|
---|
[26684] | 3 | (NEWER README FILE)
|
---|
[23883] | 4 | ==============================
|
---|
| 5 |
|
---|
| 6 | This extension helps you set up and run Greenstone3 on your android device.
|
---|
| 7 |
|
---|
| 8 | It relies on the environment variable ANDROID_SDK_HOME to determine
|
---|
[23970] | 9 | where the Android SDK lives on your file system, in a similar way
|
---|
| 10 | JAVA_HOME gets used by many programs to determin where Java is
|
---|
| 11 | installed on a particular computer. The key programs we need to run
|
---|
| 12 | from the Android SDK are 'adb' and 'dex'. The most straight forward
|
---|
| 13 | way to control this variable is to:
|
---|
[23883] | 14 |
|
---|
[23970] | 15 | cp setup-android.bash.in setup-android.bash
|
---|
| 16 |
|
---|
| 17 | and then edit 'setup-android.bash' the value of **ANDROID-SDK-HOME**
|
---|
| 18 | to be the top-level directory of where the Android SDK was installed to.
|
---|
| 19 |
|
---|
| 20 | Having done this, source the main setup file:
|
---|
| 21 |
|
---|
| 22 | source setup.bash
|
---|
| 23 |
|
---|
| 24 | which automatically sources setup-android.bash if the ANDROID_SDK_HOME
|
---|
| 25 | environment variable isn't set.
|
---|
| 26 |
|
---|
[23883] | 27 | Having sourced the setup file the two main steps are:
|
---|
| 28 |
|
---|
[26684] | 29 | 1) Install i-greenstone-server on the Android device
|
---|
| 30 | (in order to do this you must checkout on SVN the extension
|
---|
| 31 | "i-greenstone-server", which has its own seperate README.txt
|
---|
| 32 | in order to build the application)
|
---|
[23883] | 33 |
|
---|
[26684] | 34 | 2) Install Greenstone3 as a web-app application for i-greenstone-server, for
|
---|
| 35 | your Android device.
|
---|
| 36 |
|
---|
[23883] | 37 | Step 1
|
---|
[26684] | 38 | --------
|
---|
[23883] | 39 |
|
---|
[26684] | 40 | First, install i-greenstone-server on your Android device. You can do this by
|
---|
| 41 | typing in your terminal:
|
---|
[23883] | 42 |
|
---|
[26684] | 43 | adb install i-jetty-3.1-aligned.apk
|
---|
| 44 |
|
---|
[23883] | 45 | Note: for your Android device to install applications using 'adb' you
|
---|
| 46 | need to have enabled it's application 'Development' mode (under
|
---|
| 47 | Settings->Application)
|
---|
| 48 |
|
---|
[23970] | 49 | *************
|
---|
| 50 | **Important**
|
---|
| 51 | *************
|
---|
[23883] | 52 |
|
---|
[26684] | 53 | Having installed i-greenstone-server, find the application on the Android device
|
---|
| 54 | and launch it (but you don't have to go as far as starting the i-greenstone
|
---|
| 55 | server from within this application). Launching i-greenstone-server completes the
|
---|
| 56 | installation of the application by creating the 'greenstone' folder on the
|
---|
[23970] | 57 | Android's SD-card, and populating it with the default configuration
|
---|
[26684] | 58 | files for i-greenstone-server. The 'jetty' folder is needed for your
|
---|
| 59 | setup procedure as it is where Greenstone-3 will be installed to.
|
---|
[23970] | 60 |
|
---|
[23883] | 61 | Step 2
|
---|
[26684] | 62 | --------
|
---|
[23883] | 63 |
|
---|
[26684] | 64 | (This usually only needs to be done once.)
|
---|
[23883] | 65 |
|
---|
[26521] | 66 | Transfer the bulk of the <GSDL3SRCHOME>/web structure to the preparation
|
---|
| 67 | area "webapps" with the extension foler (i.e., where you are running these
|
---|
| 68 | scripts from) with:
|
---|
[23883] | 69 |
|
---|
[26521] | 70 | ./PREPARE-WEBAPPS-GREENSTONE-ROOT-FOR-IJETTY.sh
|
---|
[23883] | 71 |
|
---|
| 72 | This script skips any .svn files if present. It also skips installing
|
---|
[26521] | 73 | the majority of 'localsite' as this can be rather large -- both in
|
---|
| 74 | size and in terms of the number of files invovled -- so copying is
|
---|
| 75 | rather slow, and it is probably not what you want anyway. Only the
|
---|
| 76 | 'lucene-jdbm-demo' collection is copied to the preparation area.
|
---|
| 77 | Any other collections you wish to add should be manually added to
|
---|
| 78 | the "webapps/greenstone3/sites/localsite/collect/" area.
|
---|
[23883] | 79 |
|
---|
[26684] | 80 | Step 3
|
---|
[23883] | 81 | --------
|
---|
| 82 |
|
---|
| 83 | Convert the class files (includes those stored in jar files) into
|
---|
| 84 | classs.dex with:
|
---|
| 85 |
|
---|
[26521] | 86 | ./JAVA-TO-DEX.sh
|
---|
[23883] | 87 |
|
---|
[26521] | 88 | The finished file, which is also by this point zipped up, is stored in
|
---|
| 89 | the 'lib' folder (should you wish to inspect it). It is also
|
---|
| 90 | automatically copied to "webapps/greenstone3/WEB-INF/lib" which is
|
---|
| 91 | where it needs to be to work when installed on the Android device.
|
---|
[23883] | 92 |
|
---|
[26684] | 93 | Step 4
|
---|
[23883] | 94 | --------
|
---|
| 95 |
|
---|
[26684] | 96 | Right now we have a fresh new "webapps/greenstone3/" that we've created.
|
---|
| 97 | Now there's two things you can do - you can either create a
|
---|
| 98 | JAR file out of this webapps/greenstone3 (which is Step 4A),
|
---|
[23883] | 99 |
|
---|
[26684] | 100 | **OR**
|
---|
[23883] | 101 |
|
---|
[26684] | 102 | You can directly push the webapp into the greenstone/webapps directory
|
---|
| 103 | on the SD card of your Android phone (which is Step 4B).
|
---|
[23883] | 104 |
|
---|
[26684] | 105 | (Note: You'd probably only want to do Step 4A if you were also working with
|
---|
| 106 | the source code for i-greenstone-server.)
|
---|
[23883] | 107 |
|
---|
| 108 |
|
---|
[26684] | 109 | Step 4A
|
---|
| 110 | --------
|
---|
[23883] | 111 |
|
---|
[26685] | 112 | Assuming you have Java's bin folder already on your classpath, then
|
---|
| 113 | run the script:
|
---|
[23883] | 114 |
|
---|
[26685] | 115 | ./CREATE-WAR.sh
|
---|
[23883] | 116 |
|
---|
[26685] | 117 | The result of this script is a newly created "webapps_greenstone.war", which
|
---|
[26684] | 118 | you would put in the <GSDL3SRCHOME>/ext/i-greenstone-server/CUSTOMIZATION/assets
|
---|
| 119 | folder. That way, when it comes to compiling a fresh new i-greenstone-server,
|
---|
| 120 | it will come pre-bundled with the jar file.
|
---|
| 121 |
|
---|
| 122 |
|
---|
| 123 | **OR**
|
---|
| 124 |
|
---|
| 125 |
|
---|
| 126 | Step 4B
|
---|
| 127 | --------
|
---|
| 128 |
|
---|
| 129 | Copy Greenstone3's webapps folder onto the Android device's sd-card:
|
---|
| 130 |
|
---|
| 131 | ./IJETTY-PUSH.sh webapps/greenstone3
|
---|
| 132 |
|
---|
| 133 | This is the final step in getting Greenstone3 setup on an Andoird.
|
---|
| 134 | Switch off the USB disk mode on the Android device. Note: it can take
|
---|
| 135 | a device minute or two "preparing" the sd-card. This can be seen on
|
---|
| 136 | the notification view. Alternatively, if you try to start i-greenstone-server
|
---|
| 137 | before the card is ready, then i-greenstone-server points this out,
|
---|
| 138 | and offers you a 'retry' button.
|
---|
| 139 |
|
---|
| 140 | Launch i-greenstone-server from my apps area. Then, within i-greenstone-server,
|
---|
| 141 | start the server. Once the "Jetty started" message appears, switch to your
|
---|
| 142 | web-browser application. We've tested the built-in web browser, and
|
---|
| 143 | Mobile Firefox 4.
|
---|
| 144 |
|
---|
| 145 | By default, the URL you would navigate to is:
|
---|
| 146 | http://localhost:8080/
|
---|
| 147 |
|
---|
| 148 | As of this time of writing (10th January 2013), when you access the
|
---|
| 149 | Greenstone3 page (i.e. http://localhost:8080/greenstone3) you want to access
|
---|
| 150 | the "basic servlet", which is the 3rd link from the top.
|
---|
| 151 |
|
---|
| 152 | ====
|
---|
| 153 |
|
---|
| 154 | If the compiled Java code to Greenstone3 has changed, then you need to
|
---|
| 155 | repeat sub-steps 2.2 and 2.3. Transfering just the newly
|
---|
| 156 | dexified code can be achieved more quickly by entering:
|
---|
| 157 |
|
---|
| 158 | ./IJETTY-PUSH.sh webapps/greenstone3/WEB-INF/lib
|
---|
| 159 |
|
---|
| 160 |
|
---|
[23883] | 161 | Caveats:
|
---|
| 162 | ========
|
---|
| 163 |
|
---|
| 164 | 1. Due to difficulties in getting MG and MGPP working on android
|
---|
| 165 | through the NDK, these are currently not supported. Effectively,
|
---|
| 166 | the Greenstone3 used needs to be one compiled *without* JNI
|
---|
| 167 | support.
|
---|
| 168 |
|
---|
| 169 | 2. Due to a runtime (reflection) error, we had to modify xalan.jar.
|
---|
[26521] | 170 | The modified version of this file is also in the 'modified-jars'
|
---|
| 171 | folder used in this extension.
|
---|
[26684] | 172 |
|
---|
| 173 | 3. This Greenstone3 web app has failed to work on some phones. Upon
|
---|
| 174 | accessing an individual article in the "basic servlet" (i.e.
|
---|
| 175 | http://localhost:8080/greenstone3/basic-library) we get a stack overflow
|
---|
| 176 | error. This has not happened on newer Android phones, leading us to
|
---|
| 177 | believe that this web app may only work on Android 4.0+ OS, or on
|
---|
| 178 | newer hardware.
|
---|
[23883] | 179 |
|
---|
| 180 |
|
---|
| 181 |
|
---|
| 182 |
|
---|
| 183 |
|
---|