# Knopflerfish Android / Dalvik Tutorial

## Contents

1. Setting up the environment
2. Building Dalvik dex files
3. Creating a Dalvik KF run-time
4. Installing KF on the Android Emulator
5. Running KF under Dalvik
6. Android projects

## Setting up the Environment

To run Knopflerfish on the Android/Dalvik VM you need the Android SDK. This SDK contains the necessary tool to convert and pack Java classes and JAR files to the DEX format used by Dalvik.

The KF ant build system has built-in support for dexifying JAR files using the tools from the Android SDK.

This guide assumes the SDK for Android 4.0 API level 15 is used.

## Building Dalvik dex files

The KF ant build system has support to create the necessary dex files for the framework and all the bundles. For any bundle, the framework, or the whole KF distribution dex versions can be built by specifying `ANDROID_HOME` to the build target.

     > ant -DANDROID_HOME=>path to android sdk top directory  <

It is recommended you build the dex files on a clean distribution.

The generated dex files are places in the bundle's JAR file as `classes.dex` directly in the root. The Java class files are still kept in the JAR file. This means the same bundle can run on a normal JVM as well as with Dalvik without any modifications. From a size perspective this is of course not optimal to include both Java classes and classes.dex. A bundle get roughly twice as large after dexifying it. Future KF releases may have support to create pure dex version of bundles.

After building or dexifying KF the push the necessary files to the emulator, typically using `adb`. There is since KF 3.3 an android tool included to simplify this process, see next section.

## Creating a Dalvik KF run-time

The KF distribution contains a simple build tool to create and install KF on an Android emulator. It is located in the `tools/android` directory.

After specifying After stepping into this directory run `ant` and specify where the Android SDK is installed:

     > cd tools/android
     > ant setup -DANDROID_HOME=/Users/knopflerfish/bin/android-sdk-mac_x86/

Specifying `ANDROID_HOME` is only necessary the first time you run ant. The location is stored in the android.properties file located in the same directory. You can run the setup target again, pointing at another location if needed.

     > ant setup -DANDROID_HOME=/bin/android-sdk

There is a small template xargs file included. This contains a very basic set of bundles. Feel free to modify or add additional xargs files.

The build will create the run time in:

      > out/dalvik

## Installing KF on the Android/Dalvik Emulator

The build.xml file includes an `install` target. This will install the created KF run time on the emulator using the `adb` tools. For this to function the Android emulator must be running of course.

      > ant install

The files are installed in `/data/kf-3.3.0` by default on the emulator.

## Running KF under Dalvik

To launch KF under Dalvik you need to start Dalvik in the emulator. This is typically done by starting a shell on the emulator:

      > adb shell
      root@android:/ #
      root@android:/ # cd /data/kf-3.3.0/
      root@android:/data/kf-3.3.0 #
      root@android:/data/kf-3.3.0 # ls
      dalvik.xargs
      framework.jar
      jars
      props.xargs
      root@android:/data/kf-3.3.0 #

The next step is to launch KF. This is done as usual, but using the `dalvikvm` instead.

      root@android:/data/kf-3.3.0 # dalvikvm -classpath framework.jar \
      org.knopflerfish.framework.Main -xargs dalvik.xargs

Now KF is running under the dalvik VM! The ttyconsole bundle is included in the dalvik.xargs. In the emulator shell window you can interact with the KF framework just as you are used to:

     > lsb
       id  level/state name
       --------------------
        0  0/active    System Bundle            1  1/active    Log Service
        2  1/active    cm                       3  1/active    Console
        4  1/active    Event-Admin              5  2/resolved  util-LIB
        6  2/resolved  JSDK-API                 7  4/active    HTTP-Server
        8  5/active    FW-Commands-IMPL         9  5/active    LogCommands-IMPL
       10  5/active    CM-Commands-IMPL        11  5/active    TTY-Console-IMPL
       12  7/active    HTTP-root-IMPL
     >

To verify we are successfully running the KF HTTP server use the browser in Android emulator and connect to the KF HTTP server running on port 8080:

### Note on Running KF under Dalvik

The framework will create .dexopt files that lives side-by-side with the jar files. This can cause a problem if your bundles lives in a read-only directory and have the property (which is default):

      -Forg.knopflerfish.framework.bundlestorage.file.reference=true

You then need to set the property to false, so that the bundle jars are copied into the "fwdir".

## Android Projects

The latest version of KF added the `apk` directory to `tools/android`. Here you can find two Android projects that can be used to build an Android `.apk` containing Knopflerfish, see the README.txt file in the `projects` directory for more information.

These projects are built using a combination of KF and the Android ant tasks. Bundles that you include in your `.apk` will be dexified as described above and DEX files for `framework.jar` and Java classes included in the projects will be automatically created by the build system.