ROM building environment

Jul 9

ROM building environment

Setting up an environment for building and hacking an Android ROM can take a lot of time and be a little tricky.

Here is how I deal with that everyday on my Linux box.


  • docker build -t lollipop .
  • source sdocker
  • mkdir $HOME/Project
  • Using SeLinux ? chcon -Rt svirt_sandbox_file_t $HOME/Project
  • sdocker lollipop # Now you are inside a Docker container
  • cd /aosp/Project/
  • repo init …
  • repo sync
  • [enable ccache?]
  • source build/
  • lunch …
  • make -j12


OS version

According to the official documentation, you should use an Ubuntu 14.04.

That’s the simple way.


On the other side:

  • You want to use your favorite distribution for your daily work and not this specific Ubuntu version;
  • You may want to build a ROM for an older version depending on Ubuntu 12.04.


That’s why I’m using Docker: to have an image ready for building a specific ROM version with any kind of distribution.

Moreover, those Docker images can help when using CI/testing.

The dockerfile I use is hosted here and based on the work from Kyle Manna  plus some modifications.


The original project provides an aosp command that is able to execute a given command or script into a new Docker container.

This is useful to build a full Android, but, if you want to debug an issue and rebuild a single program, you have to reset the Android environment (source build/; lunch ..) every time.


Instead, I use the sdocker command described below that stays in the same Docker container.


Setting up Docker images

First, get the dockerfile


Build an image for Lollipop

  • docker build -t lollipop .


Kitkat build system uses a different Java version from Lollipop.

To set up a Kitkat image, you can:

  • git checkout 4.4-kitkat
  • docker build -t kitkat .


The images are ready to be run!


What’s inside Docker images?

The images have the tools needed for building (bison, curl, java …) and the “repo” tool installed.

They are configured to have some directories keeped between different run.

  • a “/tmp/ccache” directory that may be used by the excellent ccache tool and save a lot of time. If you want to use ccache, you can read the instruction here.
  • an “/aosp” directory where you can store different AOSP versions


How to run the images?

I prefer to keep the AOSP source code on my host computer so I can edit the file from my host editor.

All my projects are stored under $HOME/Project

If you are using SeLinux (like on Fedora 21), you should change some permissions so Docker can access the files:

  • chcon -Rt svirt_sandbox_file_t $HOME/Project


I also want to share my SSH agent between the host and the container.

By doing so, Git repositories protected by the SSH key from my host are also available in the container.

In short, if you want to share modifications or access a private repo, you need to have this.


I also want to connect to a running container, or start one if not already running or, create a container from an image if it does not already exist.

This can lead to a loooooong command line that I often forget across different computers

To do all that for me, I wrote a simple script command sdocker or “super-docker” 🙂


Add the content to your .zshrc or source it from there.

Bash user, should change “${=SSH_AUTH_ARGS}” into “${SSH_AUTH_ARGS}”.


And use

  • sdocker lollipop


And now?

Now, you are inside a Docker container.

The $HOME/Project folder from the host is accessible in /aosp/Project.

If you want to store your file somewhere else, you can:

  • modify sdocker
  • export the AOSP_IMAGE variable


You can get the latest Android version

  • cd /aosp/Project
  • mkdir AOSP
  • cd AOSP
  • repo init -u -b  android-5.1.1_r6
  • repo sync
  • source build/
  • lunch …
  • make -j12


If you want to share your SSH key with the container, make sure to have an SSH agent running on the host.


And if you want to go further, watch my presentation @DevFest Praha 2014 : Building Android for my Nexus.


Mathieu Maret.


  1. Rowan de Graaf
    August 20th

    I am using docker on my server. I assume the Dockerfile on your Github contains Gendy as an emulator? Is there a way to connect to that emulator with Xforwarding or whatever?

  2. Mathieu Maret
    August 24th

    I’ve only use this to build ROM for real device, so I have not connected that to an emulator.
    But, may be, you want to test an application (not a ROM)? In this case, you can have a look here :

Post A Comment