===============================================================================
                                ANDROID EXAMPLES
                  How to build and run the Scala applications
                       targeted at the Android platform
===============================================================================


This document presents the structure of the installation directory and
shortly describes the usage of the installed shell and Ant build scripts
(ant.apache.org/) to build and execute the featured Scala applications on
the Android emulator or device.


Directory structure
-------------------

The installation directory is organized as follows :

    hello-android/
        bin/
            createramdisks
            createdexlibs
            emulator
            emulator-maps
            removeramdisks
        configs/
            ant/
                ant-mac.properties
                ant-unix.properties
                ant-windows.properties
                build-scala.xml
            emulator/
                busybox.applets
                busybox.txt
                busybox.zip
                gpl-2.0.txt
                profile
            framework/
                [library.properties]
                [scala-*.jar]
                README.txt
            proguard/
                default-debug.cfg
                default-release.cfg
        build.properties
        build.xml
        README.txt
        INSTALL.txt
        <android-project-directory>/
            ... (as usual)


Shell scripts
-------------

The shell scripts are located in the "bin/" directory.

    * The wrapper scripts "emulator" and "emulator-maps" invoke the Android
      emulator with predefined values for the emulator options and the virtual
      device; furthermore they use custom ramdisk images when present (see
      the script "createramdisks" below).

    * The "createramdisks" script creates custom ramdisk images with the
      following pre-installed (and configured) software: the busybox tool
      provides additional shell commands (see note below) and the boot class
      path of the Dalvik-VM is extended with the splitted Scala libraries.

      The generated ramdisk.img files are kept in the directory
      "$ANDROID_SDK_HOME/.android/avd" and can thus be shared between all
      Android projects (they are then used by the shell scripts "emulator"
      and "emulator-maps").

    * The "createdexlibs" script converts standard .jar files to .dex files
      and saves them in the configs/framework/ directory:

      - it splits the Scala library ($SCALA_HOME/lib/scala-library.jar) into
        five smaller pieces as the dx tool fails to process a so large file,

      - it converts those .jar files into .dex files,

      - it makes a copy of the file library.properties (build version).

    * The "removeramdisks" script simply removes the customized ramdisk images
      created using "createramdisks".


Ant build scripts
-----------------

Ant build scripts are present in two locations: at the root of the installation
directory or in each project directory.

The build script "android-sdk/build.xml" features the following targets :

help:
     [echo] Android Ant Build. Available targets:
     [echo]    help:          Displays this help.
     [echo]    clean:         Removes output files created by other targets.
     [echo]    compile:       Compiles project's .java files into .class files.
     [echo]    compile-scala: Compiles project's .scala files into .class files.
     [echo]    debug:         Builds the application and signs it with a debug key.
     [echo]    release:       Builds the application. The generated apk file
     [echo]                   must be signed before it is published.
     [echo]    uninstall:     Uninstalls the application from a running
     [echo]                   emulator or device.
     [echo] Available advanced targets:
     [echo]    setenv:        Updates build files in project directories with
     [echo]                   Scala-specific data stored in the configs directory.
     [echo]    push-jars:     Installs Scala dex files onto emulator or device.
     [echo]    check-maps:    Checks configuration settings of projects
     [echo]                   depending on the Google APIs.
     [echo]    genkey:        Generates keys for signing release apk files

We ignore here the well-known targets available in standard Android projects
and focus our attention on the "scala-compile" target and the advanced targets
"setenv" and "check-maps".

    * The target "compile-scala" depends on the target "compile" (defined in
      $ANDROID_SDK_ROOT/tools/ant/main_rules.xml); it compiles
      project's .scala files into .class files.

    * The target "setenv" uses the configuration settings found in the
      directory "configs/ant/" and, when necessary, updates the files
      "local.properties", "build-scala.xml" and "configs/default-*.cfg"
      in each project directory.

    * The target "push-jars" copie the .dex files found in the local directory
      "configs/framework/" into the remote directory "/data/framework/".

    * The target "check-maps" checks the consistency of the configuration
      settings for the Google's APIs (i.e. maps.jar) defined in the project
      files "AndroidManifest.xml" and "default.properties" together with the
      environment settings of the Android emulator (or device).


===============================================================================


Note about BusyBox
------------------

In his article "The Internals of Android" (1) Frédéric Brault gives a nice
description of the installation of BusyBox, a shell toolbox for embedded
devices licensed under GPLv2, on an Android emulator or device.

The shell script "createramdisks" is inspired from that article and permits
to extend the boot class path of the Dalvik-VM with additional Java system
libraries. It was written by Stéphane Micheloud, past member of the Scala
project team (http://scala-lang.org/node/89).

Concretely, we find Java system libraries in the following two directories
(which are respectively read-only and read-write directories) when running
the Android emulator running with a customized ramdisk image:

$ adb shell /bin/ls -s /system/framework /data/framework
/system/framework:
   9 am.jar                   2647 framework.jar
  84 android.policy.jar          3 ime.jar
  74 android.test.runner.jar     2 input.jar
   6 bmgr.jar                   26 javax.obex.jar
2105 core.jar                   32 monkey.jar
 229 ext.jar                    11 pm.jar
4668 framework-res.apk         607 services.jar
   9 framework-tests.jar         4 svc.jar

/data/framework:
 187 scala-actors.jar         1106 scala-library.jar
 856 scala-collection.jar

We check that the value of the environment variable BOOTCLASSPATH is correctly
extended with the pre-installed Scala libraries. 

$ adb shell echo '$BOOTCLASSPATH'
BOOTCLASSPATH=/system/framework/core.jar:/system/framework/ext.jar:\
    /system/framework/framework.jar:/system/framework/android.policy.jar:\
    /system/framework/services.jar:/data/framework/scala-library.jar:\
    /data/framework/scala-collection.jar:/data/framework/scala-actors.jar

And we have direct access to the BusyBox commands (e.g. "/bin/ls") thanks to
the modified PATH variable: 

$ adb shell echo '$PATH'
/bin:/sbin:/system/sbin:/system/bin:/system/xbin

(1) Brault's article was published in Linux Magazine 112 under the french
    title "Les dessous d'Android" (sept. 2009) and is also available at the
    address http://www.unixgarden.com/index.php/embarque/les-dessous-dandroid.


Have fun!
The Scala Team

