Building Ubuntu Touch Android pieces from source

Whether you want to build Ubuntu Touch for the currently supported Nexus devices or want to port it to a new target, you need to set up your working environment to build Android from source. This setup is more or less the same whether you are building AOSP or a project based on it such as CyanogenMod, SEAndroid or Ubuntu Touch.

If you are new to building Android sources you may want to check out this document and others in the Getting Started section on the Google documentation site, as it covers the basics and terminology of AOSP building. While Ubuntu Touch uses some helper scripts as detailed below, if will nonetheless be helpful to understand what is going on under the hood especially if you want to work on this part of the project.

For Ubuntu Touch, you can find all the needed Android git repositories at This is basically a mirror of AOSP 4.4.2_r1, but containing only the needed low level services used by Android (e.g. no Dalvik at all).

For any Android related project on our git server, you'll find a branch named phablet-4.4.2_r1. This branch contains a static known git HEAD and the required changes needed for Ubuntu, including our custom Android manifest.

Set up your development environment

At this moment we're using the Android code base provided by Android AOSP.

Everything we take from Android is just C/C++, so you'll notice that your Android build environment will be way smaller than when comparing to the traditional Android builds.

For development you can run any 64-bit Desktop version of Ubuntu between 12.04 LTS and 13.04.

It's not strictly necessary, but it's helpful to install ccache. ( in the general Android Setup guide should help with this.)

Additional packages which are used to build the host tools:

  • $ sudo apt-get install git gnupg flex bison gperf build-essential \
      zip bzr curl libc6-dev libncurses5-dev:i386 x11proto-core-dev \
      libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-glx:i386 \
      libgl1-mesa-dev g++-multilib mingw32 tofrodos \
      python-markdown libxml2-utils xsltproc zlib1g-dev:i386 schedtool

On Utopic (and maybe other) the 4.8 version of g++ is needed:

  • $ sudo apt-get install g++-4.8-multilib

Before 14.04 Trusty you'll also need to set up the tools PPA.

Then you need to install phablet-tools:

  • $ sudo apt-get install phablet-tools

This will also install the repo tool, used to sync the Android repositories. Learn more about the repo tool. If you already have a repo tool in your $PATH from previous android development, be sure to remove it or make sure it's after the system repo command in the path. To check that the right repo command is used, you can issue $ which repo. This should return /usr/bin/repo.

You can check out the source code using the repo and git tools already familiar to Android ROM developers, as described here

Alternately, all the Android code can be downloaded using the phablet-dev-bootstrap tool provided by the phablet-tools package installed in the previous step. This tool is a Python wrapper around repo and used to also check out bzr repositories before all code was managed by repo and git. For the purposes of getting the source code for development it is no longer needed.

To get the code setup run:

  • phablet-dev-bootstrap [target_directory]

Note: You may need to specify it as:

  • phablet-dev-bootstrap --repo-branch phablet-4.4.2_r1 --sources aosp [target_directory]

If for some reason the sync ends midway, you can continue the sync with the -c switch, so the command would be:

  • phablet-dev-bootstrap -c [target_directory]

Alternatively, if you are just building an image for an already supported device, you can specify the -v switch:

  • phablet-dev-bootstrap -v [device codenames] [target_directory]

The phablet-dev-bootstrap command will automatically use the repo tool with the Ubuntu Touch Preview custom manifest to download all the git repositories and needed data. Be aware that this step takes a long time and requires at least 15GB (plus 2-3GB for the binary output).

Building for an existing device

Here's how to build Ubuntu Touch for the Nexus 4 (Android codename mako)

Since only a subset of the whole Android tree is used and built for Ubuntu Touch, the build is much faster than a full AOSP build. Still using CCACHE can help if you are doing multiple builds or have multiple target devices Build for the target you want. Valid names are mako (Nexus 4) flo (Nexus 7 2013) manta (Nexus 10) hammerhead (Neux 5) generic (Emulator).

  • $ export USE_CCACHE=1
    $ . build/
    $ lunch aosp_mako-userdebug
    $ make -j4 # Or any other amount of threads

Flashing the image

After the build out/target/product/mako will have the device specific build artifacts such as boot.img, system.img, recovery.img which can be flashed using fastboot to the respective partitions like:

  • $ fastboot flash boot boot.img
    $ fastboot flash recovery recovery.img

As our Ubuntu image is not built by the Android build system, the best approach is to just flash it directly using rootstock, like described bellow (from bootloader):

  • $ fastboot boot out/target/product/mako/recovery.img
    $ bzr branch lp:project-rootstock-ng
    $ cd project-rootstock-ng/
    $ ./rootstock-touch-install utopic-preinstalled-touch-armhf.tar.gz out/target/product/mako/system.img

You can find the latest Ubuntu rootfs image at

Updating the Android system image

Once you have a working Ubuntu Touch image on your device, do the following to update the Android system image (from bootloader):

  • $ fastboot flash boot out/target/product/mako/boot.img
    $ fastboot boot out/target/product/mako/recovery.img
    $ ./build/tools/ out/target/product/mako/system.img


Now that you are comfortable with building Ubuntu Touch and have tested it on an existing device, you may want to take another step and port it to new hardware.

Touch/Building (last edited 2015-03-05 18:08:46 by daniel-gimpelevich)