root/gs3-extensions/i-jetty/trunk/src/README.txt @ 26521

Revision 26521, 5.2 KB (checked in by davidb, 7 years ago)

Updating of text to reflect the latest version of the scripts provided by this extension

Line 
1
2Greenstone3 Runtime on Android
3==============================
4
5This extension helps you set up and run Greenstone3 on your android device.
6
7It relies on the environment variable ANDROID_SDK_HOME to determine
8where the Android SDK lives on your file system, in a similar way
9JAVA_HOME gets used by many programs to determin where Java is
10installed on a particular computer.  The key programs we need to run
11from the Android SDK are 'adb' and 'dex'.  The most straight forward
12way to control this variable is to:
13
14  cp setup-android.bash.in setup-android.bash
15
16and then edit 'setup-android.bash' the value of **ANDROID-SDK-HOME**
17to be the top-level directory of where the Android SDK was installed to.
18
19Having done this, source the main setup file:
20
21  source setup.bash
22
23which automatically sources setup-android.bash if the ANDROID_SDK_HOME
24environment variable isn't set.
25
26Having sourced the setup file the two main steps are:
27
28  1) Install i-jetty on the Android device
29
30  2) Install Greenstone3 as a web-app application on Andoird device
31
32The first step typically only needs to be done once.
33
34
35The key task for the second step is to transfer greenstone3's "web"
36directory to /sdcard/jetty/webapps/ on the Android device.  In
37principle that would be:
38
39  <GSDL3SRCHOME>/web -> <ANDROID-DEVICE>:/sdcard/jetty/webapps/greenstone3
40
41However we need to convert all the Java code (which lurks in Jar
42files) in the "web" folder into DEX-byte-code equivalents first.  We
43therefore break this step of the installation down into sub-steps (see
44below).  In overview, we create a "webapps" folder in the *extension*
45folder, where we copy the static file content of "web" to (i.e., the
46non-Java stuff).  We then top that up with Dexified versions of the
47Java code.  Finally the whole "webapps/greenstone3" folder in the
48extensions area is copied over to the Android device.
49
50
51Step 1
52=======
53
54First, install i-jetty on your Android device.  You can do this through
55the Market, or else type:
56
57  adb install i-jetty-3.1-signed-aligned.apk
58
59Note: for your Android device to install applications using 'adb' you
60need to have enabled it's application 'Development' mode (under
61Settings->Application)
62
63*************
64**Important**
65*************
66
67Having installed i-jetty, find the application on the Android device
68and launch it (but you don't have to go as far as starting the i-jetty
69server from within this application).  Launching i-jetty completes the
70installation of the application by creating the 'jetty' folder on the
71Android's SD-card, and populating it with the default configuration
72files for i-jetty.  The 'jetty' folder is needed for your setup procedure
73as it is where Greenstone-3 will be installed to.
74
75
76Step 2
77======
78
79Next put your Android device into USB disk mode, and set up the necessary files
80to run Greenstone3 as a web-app under i-jetty.  The three sub-steps are:
81
82
83Step 2.1
84--------
85
86Transfer the bulk of the <GSDL3SRCHOME>/web structure to the preparation
87area "webapps" with the extension foler (i.e., where you are running these
88scripts from) with:
89
90  ./PREPARE-WEBAPPS-GREENSTONE-ROOT-FOR-IJETTY.sh
91
92This script skips any .svn files if present.  It also skips installing
93the majority of 'localsite' as this can be rather large -- both in
94size and in terms of the number of files invovled -- so copying is
95rather slow, and it is probably not what you want anyway.  Only the
96'lucene-jdbm-demo' collection is copied to the preparation area.
97Any other collections you wish to add should be manually added to
98the "webapps/greenstone3/sites/localsite/collect/" area.
99
100Step 2.2
101--------
102
103Convert the class files (includes those stored in jar files) into
104classs.dex with:
105
106  ./JAVA-TO-DEX.sh 
107
108The finished file, which is also by this point zipped up, is stored in
109the 'lib' folder (should you wish to inspect it).  It is also
110automatically copied to "webapps/greenstone3/WEB-INF/lib" which is
111where it needs to be to work when installed on the Android device.
112
113
114Step 2.3
115--------
116
117Copy Greenstone3's webapps folder onto the Android device's sd-card:
118
119  ./IJETTY-PUSH.sh webapps/greenstone3
120
121This is the final step in getting Greenstone3 setup on an Andoird.
122Switch off the USB disk mode on the Android device.  Note: it can take
123a device minute or two "preparing" the sd-card.  This can be seen on
124the notification view.  Alternativey, if you try to start i-jetty
125before the card is ready, then i-jetty points this out, and offers you
126a 'retry' button.
127
128
129Step 3
130======
131
132Launch i-jetty from my apps area.  Then, within i-jetty, start the
133server.  Once the "Jetty started" message appears, switch to your
134web-browser application.  We've tested the built-in web browser, and
135Mobile Firefox 4.
136====
137
138If the compiled Java code to Greenstone3 has changed, then you need to
139repeat sub-steps 2.2 and 2.3.  Transfering just the newly
140dexified code can be achieved more quickly by entering:
141 
142 ./IJETTY-PUSH.sh webapps/greenstone3/WEB-INF/lib
143
144
145Caveats:
146========
147
1481. Due to difficulties in getting MG and MGPP working on android
149   through the NDK, these are currently not supported.  Effectively,
150   the Greenstone3 used needs to be one compiled *without* JNI
151   support.
152
1532. Due to a runtime (reflection) error, we had to modify xalan.jar.
154   The modified version of this file is also in the 'modified-jars'
155   folder used in this extension.
156
157
158
159
160
Note: See TracBrowser for help on using the browser.