Re: Updated Hello World tutorial & more general Kawa xml file for Android

[Per Bothner <per at bothner dot com>]

I checked in your custom_rules.xml info gnu/kawa/android.  Thanks!

I've also updated the old blog entry and merged it into the Kawa
manual, where it will be in the new Special Topics section.
(See doc/kawa.texi in the sources.)  the current draft is below.

I do plan to make some improvements to the Android support,
to make it less tedious to write layout trees.  I hope to be
able to write Scheme code equivalent to the XML layout format:
http://developer.android.com/guide/topics/ui/declaring-layout.html#write
- but of course using Scheme syntax - something like:

  (LinearLayout
    orientation: 'VERTICAL
    (TextView
       text: "Hello, I am a TextView")
    (Button
       text: "Click me!"
       on-click-listener: (lambda (e) (do-something))))

The goal is to have a slightly more interesting
"hello world" program, one with a simple event handler.

20.1 Building for Android
=========================

Google’s phone/tablet operating system Android
(https://developers.google.com/android/) is based on a custom virtual
machine on top of a Linux kernel.  Even though Android isn’t strictly
(or legally) speaking Java, you can build Android applications using
Kawa.

   Here is "Hello world" written in Kawa Scheme:

     (require 'android-defs)
     (activity hello
       (on-create-view
        (android.widget.TextView (this)
         text: "Hello, Android from Kawa Scheme!")))

   The following instructions have been tested on GNU/Linux,
specifically Fedora 17.  This link
(http://asieno.com/blog/index.php/post/2012/08/16/Setting-up-the-environment-Android-Kawa)
may be helpful if you’re building on Windows.

20.1.1 Downloading and setting up the Android SDK
-------------------------------------------------

First download the Android SDK
(http://code.google.com/android/download.html).  Unzip in a suitable
location, which we’ll refer to as ‘ANDROID_HOME’.

     export ANDROID_HOME=/path/to/android-sdk-linux
     PATH=$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools:$PATH

   Next you have to get the appropriate platform SDK:

     $ android update sdk
   You need to select an Android <q>platform</q>.  Platform (API) 16
corresponds to Android 4.1.2 (Jelly Bean).  Select that or whatever you
prefer, and click ‘Install’.  (You can install multiple platforms, but
each project is built for a specific platform.)

     ANDROID_PLATFORM=android-16

20.1.2 Building Kawa for Android
--------------------------------

Set ‘JAVA_HOME’ to where your JDK tree is.  You should use JDK 6; JDK 7
does not work at time of writing.

     $ export JAVA_HOME=/opt/jdk1.6

   First get the Kawa source code
(http://www.gnu.org/software/kawa/Getting-Kawa.html) (version 1.11 or
later).

   If using Ant (as is recommended on Windows):

     $ ant -Denable-android=true
   Alternatively, you can use ‘configure’ and ‘make’:

     $ KAWA_DIR=path_to_Kawa_sources
     $ cd $KAWA_DIR
     $ ./configure 
--with-android=$ANDROID_HOME/platforms/$ANDROID_PLATFORM/android.jar 
--disable-xquery --disable-jemacs
     $ make

20.1.3 Creating the application
-------------------------------

Next, we need to create a project or <q>activity</q>.  This tutorial
assumes you want to create the project in the target directory
‘KawaHello’, with the main activity being a class named ‘hello’ in a
package ‘kawa.android’:
     PROJECT_DIR=KawaHello
     PROJECT_CLASS=hello
     PROJECT_PACKAGE=kawa.android
     PROJECT_PACKAGE_PATH=kawa/android

   To create the project use the following command:
     $ android create project --target $ANDROID_PLATFORM --name 
$PROJECT_DIR --activity $PROJECT_CLASS --path ./$PROJECT_DIR --package 
$PROJECT_PACKAGE

   Replace the skeleton ‘hello.java’ by the Scheme code at the top of
this note, placing in a file named ‘hello.scm’:
     $ cd $PROJECT_DIR
     $ HELLO_APP_DIR=`pwd`
     $ cd $HELLO_APP_DIR/src/$PROJECT_PACKAGE_PATH
     $ rm $PROJECT_CLASS.java
     $ create $PROJECT_CLASS.scm

   We need to copy/link the Kawa jar file so the Android SDK can find
it:
     $ cd $HELLO_APP_DIR
     $ ln -s $KAWA_DIR/kawa-1.12.1.jar libs/kawa.jar

   Optionally, you can use kawart-1.12.1.jar, which is slightly smaller,
but does not support eval, and does not get built by the Ant build:
     $ ln -s $KAWA_DIR/kawart-1.12.1.jar libs/kawa.jar

   Copy or link ‘custom_rules.xml’ from the Kawa sources:
     ln -s $KAWA_DIR/gnu/kawa/android/custom_rules.xml .

   Finally to build the application just do:
     $ ant debug

20.1.4 Running the application on the Android emulator
------------------------------------------------------

First you need to create an Android Virtual Device (avd)
(http://developer.android.com/tools/devices).  Start:
     android
   Then from menu ‘Tools’ select ‘Manage AVDs...’.  In the new window
click ‘New....’ Pick a ‘Name’ (we use ‘avd16’ in the following), a
‘Target’ (to match ‘$ANDROID_PLATFORM’), and optionally change the other
properties, before clicking ‘Create AVD’.

   Now you can start up the Android emulator:

     $ emulator -avd avd16 &
   Wait until Android has finished booting (you will see the Android
home screen), click the menu and home buttons.  Now install our new
application:

     adb install bin/KawaHello-debug.apk

20.1.5 Running the application on your device
---------------------------------------------

If the emulator is running, kill it:
     $ kill %emulator

   On your phone or other Android devude, enable USB debugging.  (This
is settable from the ‘Settings’ application, under ‘Applications /
Development’.)

   Connect the phone to your computer with the USB cable.  Verify that
the phone is accessible to ‘adb’:
     $ adb devices
     List of devices attached
     0A3A560F0C015024	device

   If you don’t see a device listed, it may be permission problem.  You
can figure out which device corresponds to the phone by doing:

     $ ls -l /dev/bus/usb/*
     /dev/bus/usb/001:
     total 0
     ...
     crw-rw-rw- 1 root wheel 189, 5 2010-10-18 16:52 006
     ...

   The timestamp corresponds to when you connected the phone.  Make the
USB connection readable:
     $ sudo chmod a+w /dev/bus/usb/001/006

   Obviously if you spend time developing for an Androd phone you’ll
want to automate this process; this link
(https://sites.google.com/site/siteofhx/Home/android/drivers/udc) or
this link
(https://groups.google.com/forum/?fromgroups=#!topic/android-developers/nTfhhPktGfM)
may be helpful.

   Anyway, once ‘adb’ can talk to the phone, you install in the same way
as before:
     adb install bin/KawaHello-debug.apk

20.1.6 Some debugging notes
---------------------------

You will find a copy of the SDK documentation in
‘$ANDROID_HOME/docs/index.html’.

   If the emulator complains that your application has stopped
unexpectedly, do:
     $ adb logcat

   This shows log messages, stack traces, output from the ‘Log.i’
logging method, and other useful information.  (You can alternatively
start ‘ddms’ (Dalvik Debug Monitor Service), click on the ‘kawa.android
line’ in the top-left sub-window to select it, then from the ‘Device’
menu select ‘Run logcat....’).

   To uninstall your application, do:
     $ adb uninstall kawa.android

20.1.7 Other resources
----------------------

(A more interesting text-to-speech
(http://androidscheme.blogspot.com/2010/10/text-to-speech-app.html)
example app is on Santosh Rajan’s Android-Scheme blog
(http://androidscheme.blogspot.com/).)

   ‘https://github.com/ecraven/SchemeAndroidOGL’;

--
	--Per Bothner
per@bothner.com   http://per.bothner.com/