Gagallium

For my 25th birthday, my (awesome) friends offered me a new gadget, a Nexus 7 tablet. Of course, my first impulse was to install Debian on it. That seemed a little bit excessive; I tried to be reasonable, and decided to first try to run OCaml programs on the tablet.

I successfully managed to set up Unison on the tablet, and used it to synchronize documents between the tablet and my home computer. At the end of this blog post, hopefully you’ll be able to do the same!

These notes explain how to set up a development environment so that one can run native OCaml programs, cross-compiled to ARM, on an Nexus 7 tablet. I include quick instructions on how to root a Nexus 7 tablet, mostly because I took notes as I was doing the procedure. As some other members of Gallium are set to acquire a similar tablet soon (Luc I’m looking at you), I thought it would be helpful to write down the procedure¹.

Rooting your Nexus 7 tablet

I now give brief instructions on how to root a tablet; this was required in my case, as I couldn’t even perform a chmod on my OCaml programs to make them executable! This is actually the most complicated part. After that, setting up an OCaml cross-compiling environment is really easy.

OEM Unlocking

The “OEM Unlock” step is required before doing any sort of serious hacking with the device. This unfortunately erases all user data; but if you have chosen to sync your installed apps, after a reboot, there shouldn’t be too much stuff left to configure. Plug your device to the computer, unlock the device’s screen, enable “debugging” in the device’s options if not done already, then, on the computer, run:

sudo apt-get install android-tools-{adb,fastboot}
adb reboot bootloader
fastboot oem unlock

Please note that the tablet will ask you to confirm your computer’s RSA key the first time you use adb, so you will need to press a button on the tablet’s screen.

Becoming root on the device

The OEM unlock step does very little: it just allows you to move on to the next step: becoming root. Being root means being able to access /data/local/, put stuff in it, perform the actuals chmod, etc.

There are extra steps required to become root on the device. Several guides are available, but as usual when it comes to Android hacking, the XDA Forums contain the best source of information.

The procedure consists in installing a custom “recovery mod”; i.e. a small program that we can run before the actual operating system boots up. The whole point of it is that it has enough rights on the device so as to write anywhere; in particular, it can unzip into the sytem a “su” program that is able to make you root on the device.

Download the latest “Clockwork Mod Recovery” from the website. Also download the latest ZIP version of SuperSU (search for .zip in the forum post). Then, on your computer, with the device still connected:

adb push UPDATE-SuperSU-v1.25.zip /sdcard/
adb reboot bootloader
fastboot flash recovery recovery-clockwork-6.0.2.3-grouper.img

These steps send the to-be-installed “su” program onto the device; they reboot the tablet into the “bootloader” mode. The fastboot flash command will write the infamous “recovery mode”. Once the device is flashed, use the volume keys and the power button to switch into the said recovery mode.

At this stage, the only step left is installing the “su” program. This can be achieved using the volume keys and the power button, again. Select “flash ZIP from SDCard”, navigate, and pick the SuperSU ZIP file you previously uploaded to the device. Reboot. Voilà, you’re done.

Setting up a nice little home

After your device has rebooted, if you run adb shell, followed by su, you will gain root access to the device. You can make a little home in /data/local/, creating bin and home directories.

adb shell
su # device will prompt you the first time for confirmation
cd /data/local/
mkdir bin
mkdir home

Setting up the OCaml cross-compiler

That is actually the easiest part! Jérôme Vouillon has set up an extra opam repository ². The repository contains a README file that explains it all. For me, it was as simple as typing in my shell:

opam repo add android https://github.com/vouillon/opam-android-repository.git
opam update
opam install ocaml-android

Sample program: unison

The reason why I wanted to do all this was to run the excellent unison on my tablet, to easily synchronize music and movies. There are other programs that seem to perform a similar task, but they are either not available for Linux, or use a cloud-storage system that seems overkill / makes me uneasy.

The good news is, you can use OPAM to easily cross-compile unison.

opam install android-unison

I was then able to copy on my device the unison binary (which, fortunately, has zero external dependencies).

adb push `opam config var prefix`/arm-linux-androideabi/bin/unison /data/local/bin

After that, I can open up a shell and check that unison actually works:

adb shell # this opens up a shell on the device
su
cd /data/local/bin
export PATH=$(pwd):$PATH
export HOME=/data/local/home
unison --help

To make sure we won’t have to perform these extra steps in the future, let’s put unison in /system/xbin where it will be available for everyone to run.

adb shell # this opens up a shell on the device
su
mount -o remount,rw /system
cp /data/local/bin/unison /system/xbin/
mount -o remount,ro /system

You can then install an SSH server on your tablet (e.g. DropBear SSH), and use unison as usual.

Please note that if you want to run the unison command from an adb shell, remember to set the HOME environment variable to a suitable location, i.e. one where you can write. This is done in the sample commands above. You don’t have to worry about that when ssh’ing onto the device, as the SSH server will take care of setting a proper HOME variable.

Compile other programs

The compiler is called arm-linux-androideabi-ocamlopt. Go ahead and play with it!

Thanks and acknowledgements

The repository of Jérôme Vouillon was tremendously helpful; without it, it would’ve been probably much longer to set up a development environment.