Changeset 26684

Timestamp:

2013-01-11T15:40:23+13:00 (11 years ago)

Author:

davidb

Message:

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

Location:

gs3-extensions/android-war/trunk/src

Files:

• . (modified) (1 prop)
• README.txt (modified) (6 diffs)

gs3-extensions/android-war/trunk/src/README.txt

@@ -1 +1 @@
 
 Greenstone3 Runtime on Android
+(NEWER README FILE)
 ==============================
 
@@ -26 +27 @@
 Having sourced the setup file the two main steps are:
 
-  1) Install i-jetty on the Android device
+  1) Install i-greenstone-server on the Android device
+     (in order to do this you must checkout on SVN the extension
+     "i-greenstone-server", which has its own seperate README.txt
+     in order to build the application)
 
-  2) Install Greenstone3 as a web-app application on Andoird device
+  2) Install Greenstone3 as a web-app application for i-greenstone-server, for
+     your Android device.
+     
+Step 1
+--------
 
-The first step typically only needs to be done once. 
+First, install i-greenstone-server on your Android device. You can do this by
+typing in your terminal:
 
-
-The key task for the second step is to transfer greenstone3's "web"
-directory to /sdcard/jetty/webapps/ on the Android device.  In
-principle that would be:
-
-  <GSDL3SRCHOME>/web -> <ANDROID-DEVICE>:/sdcard/jetty/webapps/greenstone3
-
-However we need to convert all the Java code (which lurks in Jar
-files) in the "web" folder into DEX-byte-code equivalents first.  We
-therefore break this step of the installation down into sub-steps (see
-below).  In overview, we create a "webapps" folder in the *extension*
-folder, where we copy the static file content of "web" to (i.e., the
-non-Java stuff).  We then top that up with Dexified versions of the
-Java code.  Finally the whole "webapps/greenstone3" folder in the
-extensions area is copied over to the Android device.
-
-
-Step 1
-=======
-
-First, install i-jetty on your Android device.  You can do this through
-the Market, or else type:
-
-  adb install i-jetty-3.1-signed-aligned.apk
-
+  adb install i-jetty-3.1-aligned.apk
+  
 Note: for your Android device to install applications using 'adb' you
 need to have enabled it's application 'Development' mode (under
@@ -65 +51 @@
 *************
 
-Having installed i-jetty, find the application on the Android device
-and launch it (but you don't have to go as far as starting the i-jetty
-server from within this application).  Launching i-jetty completes the
-installation of the application by creating the 'jetty' folder on the
+Having installed i-greenstone-server, find the application on the Android device
+and launch it (but you don't have to go as far as starting the i-greenstone
+server from within this application).  Launching i-greenstone-server completes the
+installation of the application by creating the 'greenstone' folder on the
 Android's SD-card, and populating it with the default configuration
-files for i-jetty.  The 'jetty' folder is needed for your setup procedure
-as it is where Greenstone-3 will be installed to.
-
+files for i-greenstone-server.  The 'jetty' folder is needed for your
+setup procedure as it is where Greenstone-3 will be installed to.
 
 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
---------
+(This usually only needs to be done once.)
 
 Transfer the bulk of the <GSDL3SRCHOME>/web structure to the preparation
@@ -98 +78 @@
 the "webapps/greenstone3/sites/localsite/collect/" area.
 
-Step 2.2
+Step 3
 --------
 
@@ -111 +91 @@
 where it needs to be to work when installed on the Android device.
 
-
-Step 2.3
+Step 4
 --------
 
-Copy Greenstone3's webapps folder onto the Android device's sd-card:
+Right now we have a fresh new "webapps/greenstone3/" that we've created.
+Now there's two things you can do - you can either create a
+JAR file out of this webapps/greenstone3 (which is Step 4A),
 
-  ./IJETTY-PUSH.sh webapps/greenstone3
+**OR**
 
-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.
+You can directly push the webapp into the greenstone/webapps directory
+on the SD card of your Android phone (which is Step 4B).
+
+(Note: You'd probably only want to do Step 4A if you were also working with
+the source code for i-greenstone-server.)
 
 
-Step 3
-======
+    Step 4A
+    --------
 
-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.
-====
+    Assuming you have Java's bin folder already on your classpath, cd into
+    the folder "webapps" and then run the script:
 
-If the compiled Java code to Greenstone3 has changed, then you need to
-repeat sub-steps 2.2 and 2.3.  Transfering just the newly
-dexified code can be achieved more quickly by entering:
-  
- ./IJETTY-PUSH.sh webapps/greenstone3/WEB-INF/lib
+      ./create-jar.sh
+
+    The result of this script is a newly created "webapps_greenstone.jar", which
+    you would put in the <GSDL3SRCHOME>/ext/i-greenstone-server/CUSTOMIZATION/assets
+    folder. That way, when it comes to compiling a fresh new i-greenstone-server,
+    it will come pre-bundled with the jar file.
+    
+    
+    **OR**
+    
+    
+    Step 4B
+    --------
+
+    Copy Greenstone3's webapps folder onto the Android device's sd-card:
+
+      ./IJETTY-PUSH.sh webapps/greenstone3
+
+    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.  Alternatively, if you try to start i-greenstone-server
+    before the card is ready, then i-greenstone-server points this out, 
+    and offers you a 'retry' button.
+
+    Launch i-greenstone-server from my apps area.  Then, within i-greenstone-server, 
+    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.
+    
+    By default, the URL you would navigate to is:
+    http://localhost:8080/
+    
+    As of this time of writing (10th January 2013), when you access the
+    Greenstone3 page (i.e. http://localhost:8080/greenstone3) you want to access
+    the "basic servlet", which is the 3rd link from the top.
+    
+    ====
+
+    If the compiled Java code to Greenstone3 has changed, then you need to
+    repeat sub-steps 2.2 and 2.3.  Transfering just the newly
+    dexified code can be achieved more quickly by entering:
+      
+     ./IJETTY-PUSH.sh webapps/greenstone3/WEB-INF/lib
 
 
@@ -154 +170 @@
    The modified version of this file is also in the 'modified-jars'
    folder used in this extension.
+   
+3. This Greenstone3 web app has failed to work on some phones. Upon
+   accessing an individual article in the "basic servlet" (i.e.
+   http://localhost:8080/greenstone3/basic-library) we get a stack overflow
+   error. This has not happened on newer Android phones, leading us to
+   believe that this web app may only work on Android 4.0+ OS, or on
+   newer hardware.