Saturday, February 12, 2011

How to make an android app with SL4A and Eclipse

Having completed my first python script using sl4a on my HTC Desire I decided the next step was to create an APK (Android PacKage) to make it easier to download and run. The process is not that easy (but easier than writing the whole thing in Java) so the following explains how it was done on my PC running Windows Vista:
  • Download and install JDK from Oracle: http://www.oracle.com/technetwork/java/javase/downloads/index.html
  • Download and install Eclipse Helios: http://www.eclipse.org/downloads/ If you already have Eclipse installed make sure you have the latest updates.
  • Download and install the Android SDK http://developer.android.com/sdk/index.html If you already have the Android SDK installed make sure you have the latest updates.
  • On start up Eclipse will ask you to create a working directory. Once you have done this install the ADT plugin to Eclipse as follows: Select Help > Install New Software. Click Add, in the top-right corner. In the Add Repository dialog that appears, enter "ADT Plugin" for the Name and the following URL for the Location:  https://dl-ssl.google.com/android/eclipse/  If you have trouble acquiring the plugin, try using "http" in the Location URL, instead of "https" (https is preferred for security reasons). Click OK. In the Available Software dialog, select the checkbox next to Developer Tools and click Next. In the next window, you'll see a list of the tools to be downloaded. Click Next. Read and accept the license agreements, then click Finish.When the installation completes, restart Eclipse.
  • In Eclipse click onWindow/Preferences/Android and set the SDK location to where the SDK was installed (probably C:\Program Files\Android\android-sdk-windows).
  • Download and install Hg from mercurial: http://mercurial.selenic.com/wiki/Download 
  • Have a cup of coffee (still some way to go!)
  • Create a clone of the latest sl4a repository: Use windows explorer to create a directory where you will store the clone. Hold down the shift key and right click on the directory then open a command window. In the command window type: hg clone https://rjmatthews62-android-scripting.googlecode.com/hg/ and some time later your clone will be there. The repository gets updated regularly so use 'hg pull -u' to get and update the latest repository. Exit the command window.
  • Open Eclipse and click on File/Import/General/Existing Projects into Workspace/Next and Browse to the cloned directory. Click on Android/OK then select all and click Finish. Your screen should look like this (with lots of errors):                    [Click on view to enlarge]

  • Don't panic! First of all you don't need all projects at this stage so right click and Close Project for python, beanshell, jruby, lua, perl, rhino, tcl, InterpreterForAndroidTemplate and Documentation Generator.
  • Next include ANDROID_SDK in the Classpath Variable list by clicking Windows/Preferences/Java/BuildPathVariables/New. Put ANDROID_SDK for the name and your SDK directory for the folder (probably c:\ProgramFiles\Android\android-sdk-windows).
  • Now click Project/Build Automatically, then Project/Clean/Clean all Projects/OK. If you get error messages of files missing try Project/Build All without cleaning first. If you still have errors check if any projects have .jar entries in their libs folders which have not yet been added to the build path (right click/BuildPath/add to Build Path if not - but don't put in duplicate entries). Then try Project/Clean/Clean all Projects/OK (and maybe once more if you still have errors). Ignore the numerous warnings.
  • All these projects now comprise a working clone of SL4A. To turn your script into an APK make a copy of ScriptForAndroidTemplate (right click/copy then right click/paste into the same area). A new project will appear with the name Copy of ScriptForAndroidTemplate. To connect this project to your clone of SL4A double click on it, right click on build.xml /Run As /Ant Build. Rename the project using Refactor/Rename to whatever name you choose for your project and Refresh/Clean/Build the project.
  • Connect your phone to the PC via the USB cable, press menu, click settings/Connect to PC/Default connection type/Charge only/Done/ then press Home. If you haven't got a suitable phone set up an emulator in the Android SDK and AVD Manager (but be aware the emulator may or may not start at the first attempt and can take 10 to 20 minutes to start working the first time!).
  • Using the phone press menu again, then click settings/Applications/Development/USB debugging/OK/ then press Home. Vista should automatically find the USB driver for the phone.
  • From Eclipse install your cloned version of SL4A on your phone by clicking on ScriptingLayerForAndroid to highlight it, then Run/Run/AndroidApplication/OK.
  • With SL4A installed click on your project to highlight it then Run/Run/AndroidApplication/OK. The Console should inform you of the Android launch and a short time later you should see 'Hello Android' appear briefly on the phone (or emulator) which is the output of the default script.
  • Now you will want to tailor your project. Double click your project/res/drawable. Script_logo_48.png is the 48x48 image file that will display on your phone's screen when installed. Replace it to suit your requirements.
  • Further down from drawable double click values then strings.xml. In the xml display window click on strings.xml and change Dummy Script to your app name (must be less than 10 characters). Right click on the screen and save your change.
  • Next double click on raw and Refactor/Rename to change the name script.py to your_script_name.py then double click src/com.dummy.fooforandroid/Script.java and change  R.raw.script to R.raw.your_script_name and save.
  • Double click on src and Refactor/Rename to change the package name com.dummy.fooforandroid to your.package.name (you must have at least 2 full stops in the name). Do the same for gen (ignore the warning that the name already exists).
  • Now highlight your project then click on Project/Properties/Android select your android target and click OK
  • Towards the bottom of your project list double click on AndroidManifest.xml. Change the package name in the manifest from com.dummy.fooforandroid to your.package.name. Change your minSdkVersion from "4" to suit your android target (this is the API level for your android target shown in Project/Preferences/Android). Uncomment the permissions you require your application to have (take off <!-- at the start and  --> at the end).
  • Right click on your_script_name then open with text editor. Delete the default script, replace it with your own and save. Then Clean/Build/Refresh your project and run it. If all goes well click on File/Export to export your application as an apk. Copy the apk to your phone's sdcard, and use astro to install it.
  • Eclipse will automatically set your project to debuggable. If you want to distribute your apk open the Manifest Application and set debuggable to False. Then export again. Warn users that the interpreter for your script will also be downloaded when they install the apk.
  • All finished! Wasn't that easy!!