Prepare the environment

Long story short, don't use Windows.

So you want to make your own VM image? You brave, brave person. Before we start cranking out those builds, there is a checklist of things we will need. They are nicely documented by the kind folks at the Android open source project, so you can visit that page if you wish. Most of this is copy-pasted from there.

First of all, you will need a PC. A good one, with an absolute minimum of 2 cores running at 2GHz each and plenty of RAM, say 3-4GB. It may be possible with less but you will be waiting a looong time. The sources are over 2GB in size and growing so if you're working on DSL you'll need to factor that into consideration too. And finally, you will need an x86 or x64 architecture processor. Not too much to ask for in this day and age :)

Ok, let's talk operating systems. You're aware that Android is based on the Linux kernel, so any Linux distribution may seem like a good fit. The Android devs chose Ubuntu as their build platform which is great for me because I always use Ubuntu. I tend to use the 64-bit version because I hate not being able to use all my RAM, but unfortunately I've found it pretty much doubles the workload in terms of chasing bugs so it's better to use the 32-bit version. I'm using Jaunty at the moment but used Ibex before with no problems. They support Mac too for some reason. Maybe because they are filthy rich?

Right, lazy copy paste time.

To set up your Linux development environment, make sure you have the following:
  • Required Packages:
    • Git 1.5.4 or newer and the GNU Privacy Guard.
    • JDK 5.0, update 12 or higher.  Java 6 is not supported, because of incompatibilities with @Override.
    • flex, bison, gperf, libsdl-dev, libesd0-dev, libwxgtk2.6-dev (optional), build-essential, zip, curl.  
$ sudo apt-get install git-core gnupg sun-java5-jdk flex bison gperf libsdl-dev libesd0-dev libwxgtk2.6-dev build-essential zip curl libncurses5-dev zlib1g-dev
  • You might also want Valgrind, a tool that will help you find memory leaks, stack corruption, array bounds overflows, etc. 
$ sudo apt-get install valgrind
  • Intrepid (8.10) users may need a newer version of libreadline:
$ sudo apt-get install lib32readline5-dev

Got all that? Great. Later they mention you should get Python 2.4 too. Not sure why, but who am I to argue?

Next they want you to install their own tool, repo. Repo is like a wrapper for git, which is fine with me because I'm used to cranky old cvs and perfectly adequate subversion. If you read through the developer forums you'll find some unintentionally amusing comments about how subversion restricts your freedom. Really? I've never felt particularly oppressed by my version control software! Regardless, they use git and so we are going to be using it too, albeit with this handy tool that hides some of the horrible stuff.

Repo is a tool that makes it easier to work with Git in the context of Android. For more information about Repo, see Using Repo and Git.

To install, initialize, and configure Repo, follow these steps:

  1. Make sure you have a ~/bin directory in your home directory, and check to be sure that this bin directory is in your path:
      $ cd ~
      $ mkdir bin
      $ echo $PATH
  2. Download the repo script and make sure it is executable:
    $ curl >~/bin/repo
    $ chmod a+x ~/bin/repo

So now we have repo. As far as I can tell, it only works with the Android source. It would be nice to make a generic tool that can detect the vcs being used and do simple stuff like checkout, er, pull and synchronise code with some easy commands but whatever. Let's move on. Create a directory for your source!

  1. Create an empty directory to hold your working files:
    $ mkdir mydroid
    $ cd mydroid
  2. Run repo init to bring down the latest version of Repo with all its most recent bug fixes. You must specify a URL for the manifest:
    $ repo init -u git://
    • If you would like to check out a branch other than "master", specify it with -b, like:
      $ repo init -u git:// -b cupcake
  3. When prompted, configure Repo with your real name and email address. If you plan to submit code, use an email address that is associated with a Google account.
A successful initialization will end with a message such as
   repo initialized in /mydroid

Your client directory should now contain a .repo directory where files such as the manifest will be kept.

If you're having trouble with any of these steps, well you're SOL because they worked fine for me. You can always refer back to the original page. Helpful, am I not?

To pull down files to your working directory from the repositories as specified in the default manifest, run

   $ repo sync 

This step can take bloody ages, even if you're on a fast connection so perhaps it's time to consider having some coffee, herbal tea or a power nap.

Oh, it's finished. The Android guys think you should be able to run the build now, but that will only build the ARM version so let's move on to step 2: Building the special VirtualBox Kernel.