1 |
|
---|
2 | Greenstone3 Runtime on Android
|
---|
3 | (NEWER README FILE)
|
---|
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
|
---|
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:
|
---|
14 |
|
---|
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 |
|
---|
27 | Having sourced the setup file the two main steps are:
|
---|
28 |
|
---|
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)
|
---|
33 |
|
---|
34 | 2) Install Greenstone3 as a web-app application for i-greenstone-server, for
|
---|
35 | your Android device.
|
---|
36 |
|
---|
37 | Step 1
|
---|
38 | --------
|
---|
39 |
|
---|
40 | First, install i-greenstone-server on your Android device. You can do this by
|
---|
41 | typing in your terminal:
|
---|
42 |
|
---|
43 | adb install i-jetty-3.1-aligned.apk
|
---|
44 |
|
---|
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 |
|
---|
49 | *************
|
---|
50 | **Important**
|
---|
51 | *************
|
---|
52 |
|
---|
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
|
---|
57 | Android's SD-card, and populating it with the default configuration
|
---|
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.
|
---|
60 |
|
---|
61 | Step 2
|
---|
62 | --------
|
---|
63 |
|
---|
64 | (This usually only needs to be done once.)
|
---|
65 |
|
---|
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:
|
---|
69 |
|
---|
70 | ./PREPARE-WEBAPPS-GREENSTONE-ROOT-FOR-IJETTY.sh
|
---|
71 |
|
---|
72 | This script skips any .svn files if present. It also skips installing
|
---|
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.
|
---|
79 |
|
---|
80 | Step 3
|
---|
81 | --------
|
---|
82 |
|
---|
83 | Convert the class files (includes those stored in jar files) into
|
---|
84 | classs.dex with:
|
---|
85 |
|
---|
86 | ./JAVA-TO-DEX.sh
|
---|
87 |
|
---|
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.
|
---|
92 |
|
---|
93 | Step 4
|
---|
94 | --------
|
---|
95 |
|
---|
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),
|
---|
99 |
|
---|
100 | **OR**
|
---|
101 |
|
---|
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).
|
---|
104 |
|
---|
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.)
|
---|
107 |
|
---|
108 |
|
---|
109 | Step 4A
|
---|
110 | --------
|
---|
111 |
|
---|
112 | Assuming you have Java's bin folder already on your classpath, then
|
---|
113 | run the script:
|
---|
114 |
|
---|
115 | ./CREATE-WAR.sh
|
---|
116 |
|
---|
117 | The result of this script is a newly created "webapps_greenstone.war", which
|
---|
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 |
|
---|
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.
|
---|
170 | The modified version of this file is also in the 'modified-jars'
|
---|
171 | folder used in this extension.
|
---|
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.
|
---|
179 |
|
---|
180 |
|
---|
181 |
|
---|
182 |
|
---|
183 |
|
---|