Knopflerfish Android / Dalvik Tutorial

Setting up the environment
Building Dalvik dex files
Creating a Dalvik KF run-time
Installing KF on the Android Emulator
Running KF under Dalvik
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.

Android
application

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.