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:
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 installThe 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.xargsNow 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
You then need to set the property to false, so that the bundle jars
are copied into the "fwdir".
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.