root/gs3-extensions/android-war/trunk/src/README.txt @ 26684

Revision 26684, 6.2 KB (checked in by davidb, 7 years ago)

README.txt updated to reflect the most recent set of changes. The 'apk' now comes from the 'i-greenstone-server' extension, set up here as an external reference

Line 
1
2Greenstone3 Runtime on Android
3(NEWER README FILE)
4==============================
5
6This extension helps you set up and run Greenstone3 on your android device.
7
8It relies on the environment variable ANDROID_SDK_HOME to determine
9where the Android SDK lives on your file system, in a similar way
10JAVA_HOME gets used by many programs to determin where Java is
11installed on a particular computer.  The key programs we need to run
12from the Android SDK are 'adb' and 'dex'.  The most straight forward
13way to control this variable is to:
14
15  cp setup-android.bash.in setup-android.bash
16
17and then edit 'setup-android.bash' the value of **ANDROID-SDK-HOME**
18to be the top-level directory of where the Android SDK was installed to.
19
20Having done this, source the main setup file:
21
22  source setup.bash
23
24which automatically sources setup-android.bash if the ANDROID_SDK_HOME
25environment variable isn't set.
26
27Having 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     
37Step 1
38--------
39
40First, install i-greenstone-server on your Android device. You can do this by
41typing in your terminal:
42
43  adb install i-jetty-3.1-aligned.apk
44 
45Note: for your Android device to install applications using 'adb' you
46need to have enabled it's application 'Development' mode (under
47Settings->Application)
48
49*************
50**Important**
51*************
52
53Having installed i-greenstone-server, find the application on the Android device
54and launch it (but you don't have to go as far as starting the i-greenstone
55server from within this application).  Launching i-greenstone-server completes the
56installation of the application by creating the 'greenstone' folder on the
57Android's SD-card, and populating it with the default configuration
58files for i-greenstone-server.  The 'jetty' folder is needed for your
59setup procedure as it is where Greenstone-3 will be installed to.
60
61Step 2
62--------
63
64(This usually only needs to be done once.)
65
66Transfer the bulk of the <GSDL3SRCHOME>/web structure to the preparation
67area "webapps" with the extension foler (i.e., where you are running these
68scripts from) with:
69
70  ./PREPARE-WEBAPPS-GREENSTONE-ROOT-FOR-IJETTY.sh
71
72This script skips any .svn files if present.  It also skips installing
73the majority of 'localsite' as this can be rather large -- both in
74size and in terms of the number of files invovled -- so copying is
75rather slow, and it is probably not what you want anyway.  Only the
76'lucene-jdbm-demo' collection is copied to the preparation area.
77Any other collections you wish to add should be manually added to
78the "webapps/greenstone3/sites/localsite/collect/" area.
79
80Step 3
81--------
82
83Convert the class files (includes those stored in jar files) into
84classs.dex with:
85
86  ./JAVA-TO-DEX.sh 
87
88The finished file, which is also by this point zipped up, is stored in
89the 'lib' folder (should you wish to inspect it).  It is also
90automatically copied to "webapps/greenstone3/WEB-INF/lib" which is
91where it needs to be to work when installed on the Android device.
92
93Step 4
94--------
95
96Right now we have a fresh new "webapps/greenstone3/" that we've created.
97Now there's two things you can do - you can either create a
98JAR file out of this webapps/greenstone3 (which is Step 4A),
99
100**OR**
101
102You can directly push the webapp into the greenstone/webapps directory
103on 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
106the 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, cd into
113    the folder "webapps" and then run the script:
114
115      ./create-jar.sh
116
117    The result of this script is a newly created "webapps_greenstone.jar", 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
161Caveats:
162========
163
1641. 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
1692. 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   
1733. 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
Note: See TracBrowser for help on using the browser.