This page aims to give all the information needed to compile and operate COMET. For OSDI 2012 paper click here.

Initializing your build environment

Follow the directions listed on the AOSP website. COMET is currently based on version 4.1.x (Jellybean) of Android. In particular this means you will need a 64-bit build environment.

Downloading COMET

Downloading COMET is almost the same as downloading the source code from the Android Open Source Project. Follow the directions on the AOSP page up to the "Getting the files" section. However use the below command to initialize your repository instead of the one listed in the link.

repo init -u https://github.com/msg555/comet_android -b jellybean

It may take several hours for this step to complete.

Compiling for the first time

The steps involved in compiling the entire Android stack with COMET will vary from device to device. The easiest thing to do will be to find a CM-10 image from the CyanogenMod website. When you find your device make sure you note the codename of the device which will be listed on the CyanogenMod website. For instance you can download CM-9 for the Galaxy Nexus (GSM) from here and the page indicates the code name is 'maguro'.

When you have the CM-10 image installing it on your phone is up to you. You can find a lot of useful information from the CyanogenMod Wiki or by just googling around. Completing this step will likely require you to root your phone and void any warranty on the device.

After CM-10 has been installed you can optionally choose to compile the whole CyanogenMod stack from your source repository. Before you can start building you need to grab any proprietary drivers and software. You should be able to find a file called 'extract-files.sh' in your device folder corresponding to your device. With your device plugged in (running CM-10) issue the following commands from the root of your repository (replace the directions for maguro with your device)

vendor/cm/get-prebuilts
cd device/samsung/maguro
./extract-files.sh
cd -

Now you're ready to compile! As a rule, before issuing any make command or running any commands in the 'scripts' directory, make sure you have sourced in your build environment. On xterm you should be able to check if you've done this already by checking if the title of the terminal starts with the build setup you chose. To source in the build environment run the commands

. build/envsetup.sh
lunch

At this point you will be presented with a menu. Select the menu item that matches the codename of the device you are using. Now you're ready to build. To build everything run the following command.

make -j10 otapackage

This will produce a zip file like what you got from the CyanogenMod website for you to install. The last line will indicate where this zip was written to on your machine. It's not actually required that you install this new zip file however some of the things we built will be needed later on.

Building COMET

Now you're ready to build the VM with COMET enabled. Again, make sure you have the build environment sourced in. To select COMET to be installed run the following command.

scripts/switch_vm.sh offload
scripts/clean_vm.sh

If you're interested in building the VM without COMET in the future swap out 'none' for 'offload' in the above commands. If you wish to build COMET with debugging code use 'offload-debug' instead. To actually build COMET issue the following command

make -j10 libdvm

After compilation completes you can push the new version of the VM onto the phone with the command

scripts/push_vm.sh

If for some reason something fails to push it's likely because either your phone is not plugged in or the component hasn't been built. In the later case you can have make compile the single component directly by running 'make component_name'. For components that have extensions (.jar files) just strip off the extension.

Setting up your server

You're almost ready to use COMET. Currently the only mechanism to configure the server the phone connects to is by editing the file scripts/30tcpmux and then running push_vm.sh again. For example if your server IP address is 12.34.56.78 then you should make your 30tcpmux file look like

#!/system/bin/sh

if [ -e /system/bin/tcpmux ];
then
  tcpmux --daemon --control 5554 --retry 5555 12.34.56.78:5556
fi;

The rest of the commands are to be run from the vm_test folder. First you need to setup your server environment. Run the following commands with your device plugged in.

./setup_links.sh
./setup_server.sh myconfig prepare

With your environment setup, running the server requires running two daemons. The first is the tcpmux daemon responsible for multiplexing connections over one connection for all client VMs and handling disconnections gracefully. To run this in the background you can run the command

system/bin/tcpmux --daemon --demux 5556 localhost:12345

Note that if you shut this daemon down the phone will need to restart before it can connect again at the moment. Finally you need to start up the server VM with the command

./stdrunserv.sh 5556 12345

and you should be good to go. Make sure you do not use the runserv.sh script to start up the server. This script is meant for use in local testing.