Changeset 26684

Show
Ignore:
Timestamp:
11.01.2013 15:40:23 (6 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:
2 modified

Legend:

Unmodified
Added
Removed
  • gs3-extensions/android-war/trunk/src

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

    r26521 r26684  
    11 
    22Greenstone3 Runtime on Android 
     3(NEWER README FILE) 
    34============================== 
    45 
     
    2627Having sourced the setup file the two main steps are: 
    2728 
    28   1) Install i-jetty on the Android device 
     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) 
    2933 
    30   2) Install Greenstone3 as a web-app application on Andoird device 
     34  2) Install Greenstone3 as a web-app application for i-greenstone-server, for 
     35     your Android device. 
     36      
     37Step 1 
     38-------- 
    3139 
    32 The first step typically only needs to be done once.  
     40First, install i-greenstone-server on your Android device. You can do this by 
     41typing in your terminal: 
    3342 
    34  
    35 The key task for the second step is to transfer greenstone3's "web" 
    36 directory to /sdcard/jetty/webapps/ on the Android device.  In 
    37 principle that would be: 
    38  
    39   <GSDL3SRCHOME>/web -> <ANDROID-DEVICE>:/sdcard/jetty/webapps/greenstone3 
    40  
    41 However we need to convert all the Java code (which lurks in Jar 
    42 files) in the "web" folder into DEX-byte-code equivalents first.  We 
    43 therefore break this step of the installation down into sub-steps (see 
    44 below).  In overview, we create a "webapps" folder in the *extension* 
    45 folder, where we copy the static file content of "web" to (i.e., the 
    46 non-Java stuff).  We then top that up with Dexified versions of the 
    47 Java code.  Finally the whole "webapps/greenstone3" folder in the 
    48 extensions area is copied over to the Android device. 
    49  
    50  
    51 Step 1 
    52 ======= 
    53  
    54 First, install i-jetty on your Android device.  You can do this through 
    55 the Market, or else type: 
    56  
    57   adb install i-jetty-3.1-signed-aligned.apk 
    58  
     43  adb install i-jetty-3.1-aligned.apk 
     44   
    5945Note: for your Android device to install applications using 'adb' you 
    6046need to have enabled it's application 'Development' mode (under 
     
    6551************* 
    6652 
    67 Having installed i-jetty, find the application on the Android device 
    68 and launch it (but you don't have to go as far as starting the i-jetty 
    69 server from within this application).  Launching i-jetty completes the 
    70 installation of the application by creating the 'jetty' folder on the 
     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 
    7157Android's SD-card, and populating it with the default configuration 
    72 files for i-jetty.  The 'jetty' folder is needed for your setup procedure 
    73 as it is where Greenstone-3 will be installed to. 
    74  
     58files for i-greenstone-server.  The 'jetty' folder is needed for your 
     59setup procedure as it is where Greenstone-3 will be installed to. 
    7560 
    7661Step 2 
    77 ====== 
     62-------- 
    7863 
    79 Next put your Android device into USB disk mode, and set up the necessary files 
    80 to run Greenstone3 as a web-app under i-jetty.  The three sub-steps are: 
    81  
    82  
    83 Step 2.1 
    84 -------- 
     64(This usually only needs to be done once.) 
    8565 
    8666Transfer the bulk of the <GSDL3SRCHOME>/web structure to the preparation 
     
    9878the "webapps/greenstone3/sites/localsite/collect/" area. 
    9979 
    100 Step 2.2 
     80Step 3 
    10181-------- 
    10282 
     
    11191where it needs to be to work when installed on the Android device. 
    11292 
    113  
    114 Step 2.3 
     93Step 4 
    11594-------- 
    11695 
    117 Copy Greenstone3's webapps folder onto the Android device's sd-card: 
     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), 
    11899 
    119   ./IJETTY-PUSH.sh webapps/greenstone3 
     100**OR** 
    120101 
    121 This is the final step in getting Greenstone3 setup on an Andoird. 
    122 Switch off the USB disk mode on the Android device.  Note: it can take 
    123 a device minute or two "preparing" the sd-card.  This can be seen on 
    124 the notification view.  Alternativey, if you try to start i-jetty 
    125 before the card is ready, then i-jetty points this out, and offers you 
    126 a 'retry' button. 
     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.) 
    127107 
    128108 
    129 Step 3 
    130 ====== 
     109    Step 4A 
     110    -------- 
    131111 
    132 Launch i-jetty from my apps area.  Then, within i-jetty, start the 
    133 server.  Once the "Jetty started" message appears, switch to your 
    134 web-browser application.  We've tested the built-in web browser, and 
    135 Mobile Firefox 4. 
    136 ==== 
     112    Assuming you have Java's bin folder already on your classpath, cd into 
     113    the folder "webapps" and then run the script: 
    137114 
    138 If the compiled Java code to Greenstone3 has changed, then you need to 
    139 repeat sub-steps 2.2 and 2.3.  Transfering just the newly 
    140 dexified code can be achieved more quickly by entering: 
    141    
    142  ./IJETTY-PUSH.sh webapps/greenstone3/WEB-INF/lib 
     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 
    143159 
    144160 
     
    154170   The modified version of this file is also in the 'modified-jars' 
    155171   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. 
    156179 
    157180