Cells: Download and Build

Cells is Open Source

Most of the Cells project has now been released under the terms of the GNU GPL. The code is released as a complete set of Android git repositories that initially targets the Asus Nexus 7 (grouper). Building Cells is similar to building other Android releases such as AOSP or CyanogenMod, and our full Gerrit review site allows easy collaboration with the community. The Cells source include a complete Android distribution, a Cells-enabled kernel, and custom user space utilities for creating and managing virtual Android instances. You can browse the code online here: https://cells-source.cs.columbia.edu/.

We recommend reading through all of the following instructions before beginning. Happy hacking!

Initialize Your Environment

Before beginning the download and build process, you will need to setup your environment for an Android build. This setup is well-described by the Android Open Source Project. The requirements are the same for building Cells. We have tested the build on OS X Mountain Lion as well as a variety of Linux distributions. For brevity, we provide only the necessary commands and a basic description where the details are the same as the standard Android build system.

Download and Build

Tool Setup

You will need Google’s repo tool to download the set of Android repositories:
$ curl curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
$ chmod a+x ~/bin/repo
$ mkdir cells && cd cells
NOTE repo v1.12.4 has an incorrectly signed tag which may cause issues if you are downloading code for the first time. To bypass this issue (and to successfully update an existing installation), you can use a repo script from commondatastorage:
curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo

Download Cells

You can freely download the Cells code using anonymous https, however, if you plan on contributing to the Cells project, you need to be a registered developer. See the instructions on contributing to Cells, and download the code using SSH.To save on bandwidth and local disk space, we have organized the repositories into groups. For example, when building on Linux it is not necessary to include all of the prebuilt Darwin toolchains, and vice-versa. You can pass a set of comma-separated groups to the repo init command. The current supported groups are:
  • common – all the common source code and repositories
  • linux – supporting binary tools necessary for a build on a Linux system
  • darwin – supporting binary tools necessary for a build on OSX
  • grouper – necessary repositories for the Nexus 7 (grouper)
  • aosp – all repositories contained in the Android Open Source Project
The general format for initializing the Cells source code is:
$ repo init -u https://cells-source.cs.columbia.edu/platform/manifest -b [BRANCH] -g [GROUPS]

where:

  • [BRANCH] will specify the Android release. Currently only cells-jb is supported for the Jelly Bean (4.3) build.
  • [GROUPS] is the comma-separated list of repository groups, e.g.,common,darwin,grouper for building on OSX, and common,linux,grouper for building on Linux.
We recommend the following repo initialization commands for building on Linux and OS X (respectively):
$ repo init -u https://cells-source.cs.columbia.edu/platform/manifest -b cells-jb -g common,linux,grouper
$ repo init -u https://cells-source.cs.columbia.edu/platform/manifest -b cells-jb -g common,darwin,grouper
After initializing the Cells source with one of the two above commands, you can download the code using:
$ repo sync

For network trouble shooting issues and tips on saving network bandwidth, please refer to the Android source download page.

NOTE On some Linux installations, git may fail to verify the SSL certificate of cells-source.cs.columbia.edu. The issue is addressed on this StackOverflow thread, and can be solved using the following commands:
wget http://cert.incommon.org/InCommonServerCA.crt
openssl x509 -inform DER -in InCommonServerCA.crt -out incommon.pem
cat /etc/ssl/certs/ca-certificates.crt incommon.pem > ca-certs2.crt
sudo cp /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt.bak
sudo cp ca-certs2.crt /etc/ssl/certs/ca-certificates.crt

Configure the Build

After the code has been completely downloaded (this may take a while), a shell script named source-me.sh should be in the top-level directory. You can source this file and pass an Android lunch combo (full_grouper-eng for the Nexus 7) to setup your build environment. You will need to do this every time you start working with the Cells code (or open a new terminal). The source-me.sh sets up some Cells specific environment commands and then automatically sources the Android environment setup script. See the Cells environment reference for environment variables you can set to avoid the source-me.sh prompts.
$ source ./source-me.sh full_grouper-eng
NOTE the -eng can be replaced with -user or -userdebug depending on the type of build you want. Build types are documented here.
OS X Users you will need the latest version of XCode. Using older toolchains may work, but is unsupported; setting the following environment variable may help: export TARGET_GCC_VERSION_EXP=4.6

Start the Build

$ make -j4
This will build everything including a complete Android runtime, a Cells-enabled kernel, and all appropriate tools and modules.
NOTE For convenience we have included all necessary binary drivers for the Nexus 7 (available here), and the Google apps (available here). None of these binary drivers or applications are supported in any way by the Cells team, or by Columbia University.

Flash the device

The build process results in several image files that can be flashed onto your Nexus 7 device. You can use Google’s fastboot tool (which you actually just built), or the Cells custom aflash command.

Please DO NOT attempt to flash any device other than an Asus Nexus 7 code-named “grouper”. This code WILL NOT work on the newer 2013 Nexus 7 from Samsung!

The following two commands are equivalent (see the Cells environment reference for more information on the aflash utility):

$ fastboot flashall -w
$ aflash

This will flash the Cells system you just built onto your device. NOTE there is no GUI on the device yet! Your device should automatically reboot, and it will appear to be “stuck” at the logo screen. Make sure you can get a shell on the device using adb:

$ adb shell

Starting Cells

In the current prototype, the only way to manipulate virtual Android instances, or Cells, is through the standard Android adb shell, i.e., the device must be connected to your PC.With a root shell on the “host” system, you can now use the command-line cell utility to create, destroy, start, stop, and configure your Cells! Please refer to the built-in help for more info:

# cell -h
Here is a quick set of commands that creates two Cells, starts them and makes sure they automatically start after you reboot:
# cell create home
# cell create work
# cell autoswitch home on
# cell start home -D -s
# cell autostart home on
# cell start work -D -s
# cell autostart work on

Done

Now that you have started up one or more Cells on your device, you can manipulate them with the cell utility through adb, and you can also switch between them using a key combo. When the VOLUME_UP and VOLUME_DOWN buttons are pressed simultaneously, the system switches to the next available Cell. This allows you to switch between Cells without being connected to a PC.For convenience we have included Google Apps including GMail, Google+, and the Google Play store. When you first start a Cell you will be prompted to setup a Google account. You can register different Google accounts in different Cells, and use them to download and install different applications from the Google Play store.

Known Issues

This is a list of known issues with the current open source release:
  • Jelly Bean uses a large amount of memory, and starting two (or more instances) can quickly consume all the available RAM – especially on first boot as none of the Android applications have been pre-optimized. To mitigate this, you can wait for a single Cell to boot before starting a second, and you can also use the -H option when starting a Cell (see cell start -h). The -H option configures celld to share the optimized Dalvik cache directory amongst all running Cells potentially saving many megabytes of duplicated filesystem cache.
  • When switching between Cells it is sometimes necessary to touch the screen to force the newly active Cell to re-draw. If the newly active Cell had previously put itself to sleep, it may also be necessary to press the POWER button.
  • The Tegra display controller virtualization can sometimes cause on-screen flicker in the active Cell when background Cells are present. This is being actively investigated.
  • This release of Cells does not support telephony, thus it is not possible to assign unique phone numbers to each Cell.

Columbia University Department of Computer Science