Setting Up Your Build Environment

Operating System

If you have a linux box or virtual machine to use, you may skip this section. However it may be worthwhile to double check that the configuration is correct for your machine.

If you're running Windows, you can either: get a separate linux machine or create a virtual machine. Windows is not currently supported for building 
The latter option is available to UTEP students with VMWare - a virtual box application. It can be downloaded here:
  • Note: you need to create an account at the above link, which is a two step process: 1)request an account by clicking on "Sign In" > "Register" > "Request an Account". 2) After an admin approves the request, an account can be registered via its username.
  • Notice that certain types of unix/linux systems are suggested here to maximize compatibility. Ubuntu 10.04 (Lucid Lynx) is the suggested choice, isos of the 64bit (amd64) desktop version can be found here. Look for "ubuntu-10.04.3-desktop-amd64.iso".

Ports for XServer access to VM (Optional)

By default, the windows firewall blocks all access to ports created for VMs. To allow connections to a VM host, there is a workaround that we made here. Not doing this portion will prevent X servers and other local ssh connections to the VM.

Tutorials that already exist about Build environments and downloading source code

It would be worth your while to read over the following pages if you'd like. The majority of their content has been assimilated into this tutorial (I also corrected some info that was out of order or just missing from one or the other).
Please note that the following set of pages is currently device dependent on the Samsung Galaxy Nexus, although similar pages could be found for other phone models.
Again, I've included the relevant info from these pages into this tutorial; the above pages differ or omit some points, which I will try to combine properly.

The Tutorial

I have divided the following tutorial up into several sections, each of which with some bold header in a bold black font. Please read all of the content within each section before running any of the commands listed there, as some commands have circumstantial info that you may need to know before running the command. There will be more warnings along the way - don’t worry, though, I tried to group as much related info as necessary to get you through the process.

What you’ll need

  • A relatively recent computer (Linux, OS X, or Windows) w/a reasonable amount of RAM and storage. The less RAM you have, the longer the build will take. Using SSDs results in faster builds than traditional hard drives.

  • A micro USB cable

  • A decent Internet connection & reliable electricity :)

  • Some familiarity with basic Android operation and terminology. It would help if you’ve installed custom roms on other devices and are familiar with what a recovery image such as ClockworkMod is, for example. It may also be useful to know some basic command line concepts such as cd for “change directory”, the concept of directory hierarchies, that in Linux they are separated by /, etc.

Windows Setup

Find the following files with the search engine of your choice (seriously though, just Google it).

  1. Windows' MTP porting kit aka Media Transfer Protocol porting kit

    • download it straight from microsoft
      Note: Windows’ MTP porting kit requires a valid version of windows in order to be downloaded. In case you don’t have a valid copy of Windows, please talk to Gabriel about downloading it from an “alternate source”.

  2. latest version of "samsung usb drivers for mobile phones"

    • download it from any trusted file server

  3. pdaneta302x64.exe

Linux Basic Setup

A helpful Note: Try to keep just one terminal session, as variables are created as part of the build process; so closing a terminal may include destroying some temporary variables used by scripts within the build process. That being said, open up a terminal with Ctrl+Alt+T (on Ubuntu) and enter the following:

$ sudo apt-get install ia32-libs

Create the Directories

Note: The directory structure used when building with CyanogenMod is very fragile, so follow these directions closely, or you may end up voiding the scripts you will be running later.


You will need to set up some directories in your build environment.

To create them:

$ mkdir -p ~/bin $ mkdir -p ~/android/system


Install ADT

Download the latest ADT package for the Android SDK here:

http://developer.android.com/sdk/index.html

Select the option near the bottom of the page to “Download for other platforms” and select the appropriate version for linux. If you are using windows, it’s suggested that you also install the sdk on windows as well. The site contains installation instructions here:

http://developer.android.com/sdk/installing/bundle.html

However, the instructions above boil down to, ‘unzip the ADT bundle into the directory of your choice; be sure to remember (i.e., write down) the directory where you unzip ADT into.


Include

    ~/bin

and

    sdk/platform-tools

in your environment path (requires a restart for the path to reset). Also, make sure adb and fastboot work from the path with the following command:

$ adb devices


If you receive an adb command not found message, you have not set up your path correctly. This can be verified by entering the following in the terminal:

$ echo $PATH

You should NOT see the folders ~/bin and the path to your ADT package within the printed string. If you do see the folders within the string, try running the following command again:

$ sudo apt get install ia32-libs


If the PATH is indeed missing the folders mentioned above, you can:

  • set the path temporarily with the following command: $ export PATH=$PATH:~/bin:/path/to/the/ADT/folder 
  • Or add the line above this one (without the prompt symbol $) to the .bashrc file and restart the terminal. If the path still doesn't include the correct folders, try restarting your linux machine.

Get java from the correct repo

Orcale/Sun's java has to be used, which is not the default java used. You have to add their repository to the apt-get repos and download it from them. Back in your terminal, run the following:

$ sudo add-apt-repository ppa:webupd8team/java

$ sudo apt-get update

$ sudo apt-get install oracle-java6-installer

                       

Check the java version with "java -version". It should return:

java version "1.6.0_45"

Java(TM) SE Runtime Environment (build 1.6.0_45-b06)

Java HotSpot(TM) 64-Bit Server VM (build 20.45-b01, mixed mode)


You will also need the following programs:

  • Python 2.6 -- 2.7, which you can download from python.org

  • GNU Make 3.81 -- 3.82, which you can download from gnu.org

Note: these two should be installed into Ubuntu by default, and can be verified with the following commands, respectively:

$ python --version

$ make --version

Some more applications and setup:

Run the following commands:


The following only on Ubuntu 10.04:

$ sudo apt-get install git-core gnupg flex bison gperf build-essential zip curl zlib1g-dev libc6-dev lib32ncurses5-dev ia32-libs x11proto-core-dev libx11-dev lib32readline5-dev lib32z-dev libgl1-mesa-dev g++-multilib mingw32 tofrodos python-markdown libxml2-utils xsltproc

                           


The following only on Ubuntu 12.04:

$ sudo apt-get install git gnupg flex bison gperf build-essential zip curl libc6-dev libncurses5-dev:i386 x11proto-core-dev libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-dev g++-multilib mingw32 tofrodos python-markdown libxml2-utils xsltproc zlib1g-dev:i386
$ sudo ln -s /usr/lib/i386-linux-gnu/mesa/libGL.so.1 /usr/lib/i386-linux-gnu/libGL.so

     A note on the above command: the package "libgl1-mesa-glx:i386" was part of the above list of programs, however with Ubuntu 12.04 (the exact distro of Ubuntu that AOSP suggests installing the package into), the desktop environment gets removed, leaving users with a broken Ubuntu system the next time they boot their machine. If you download the package via apt-get download instead of apt-get install, manually tring to install it shows the following output:

libgl1-mesa-glx:i386 conflicts with libgl1
  libgl1-mesa-glx-lts-quantal:i386 provides libgl1 and is present and installed.
  libgl1-mesa-glx-lts-quantal provides libgl1 and is present and installed.

Meaning that the package is already installed in a different form. So avoid installing this package at all costs! (This is also an excellent reason for snapshotting your system from time to time)


     On all systems: (the following 2 commands)

$ sudo apt-get install git-core gnupg flex bison gperf libsdl1.2-dev libesd0-dev libwxgtk2.8-dev squashfs-tools build-essential zip curl libncurses5-dev zlib1g-dev openjdk-6-jre openjdk-6-jdk pngcrush schedtool libxml2 libxml2-utils xsltproc          


$ sudo apt-get install g++-multilib lib32z1-dev lib32ncurses5-dev lib32readline-gplv2-dev gcc-multilib

                            OR if that fails,

$ sudo apt-get install g++-multilib lib32z1-dev lib32ncurses5-dev libreadline-dev gcc-multilib


Put the following in your .bashrc or equivalent.

export USE_CCACHE=1


After installing git, your username and email should be set with the following commands:

  • $ git config --global user.name "User name"

  • $ git config --global user.email user@example.com

Linux and Android USB connections

Under GNU/linux systems (and specifically under Ubuntu systems), regular users can't directly access USB devices by default. The system needs to be configured to allow such access. The recommended approach is to create a file /etc/udev/rules.d/51-android.rules (as the root user) and to copy the following lines in it. <username> must be replaced by the actual username of the user who is authorized to access the phones over USB.

# adb protocol on passion (Nexus One)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e12", MODE="0600", OWNER="<username>"

# fastboot protocol on passion (Nexus One)

SUBSYSTEM=="usb", ATTR{idVendor}=="0bb4", ATTR{idProduct}=="0fff", MODE="0600", OWNER="<username>"

# adb protocol on crespo/crespo4g (Nexus S)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e22", MODE="0600", OWNER="<username>"

# fastboot protocol on crespo/crespo4g (Nexus S)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e20", MODE="0600", OWNER="<username>"

# adb protocol on stingray/wingray (Xoom)

SUBSYSTEM=="usb", ATTR{idVendor}=="22b8", ATTR{idProduct}=="70a9", MODE="0600", OWNER="<username>"

# fastboot protocol on stingray/wingray (Xoom)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="708c", MODE="0600", OWNER="<username>"

# adb protocol on maguro/toro (Galaxy Nexus)

SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", ATTR{idProduct}=="6860", MODE="0600", OWNER="<username>"

# fastboot protocol on maguro/toro (Galaxy Nexus)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e30", MODE="0600", OWNER="<username>"

# adb protocol on panda (PandaBoard)

SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d101", MODE="0600", OWNER="<username>"

# fastboot protocol on panda (PandaBoard)

SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d022", MODE="0600", OWNER="<username>"

# usbboot protocol on panda (PandaBoard)

SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d00f", MODE="0600", OWNER="<username>"

# usbboot protocol on panda (PandaBoard ES)

SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d010", MODE="0600", OWNER="<username>"

# adb protocol on grouper/tilapia (Nexus 7)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e42", MODE="0600", OWNER="<username>"

# fastboot protocol on grouper/tilapia (Nexus 7)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e40", MODE="0600", OWNER="<username>"

# adb protocol on manta (Nexus 10)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4ee2", MODE="0600", OWNER="<username>"

# fastboot protocol on manta (Nexus 10)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4ee0", MODE="0600", OWNER="<username>"

# fastboot protocol on glacier (HTC myTouch 4G) SUBSYSTEM=="usb", ATTR{idVendor}=="0bb4", ATTR{idProduct}=="0c96", MODE="0600", OWNER="<username>"


To add a new devices to the list, run the following command:

$ lsusb

You should get something like this:

Bus 001 Device 007: ID 22b8:2e63 Motorola PCS

Bus 002 Device 004: ID 80ee:0021 VirtualBox USB Tablet Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub

The first line is my android device. Highlighted in green is the idVendor and highlighted in blue is idProduct.

Create a new entry at the end of the file for your device using the correct idVendor and idProduct and save the changes.

SUBSYSTEM=="usb", ATTR{idVendor}=="80ee", ATTR{idProduct}=="0021", MODE="0600", OWNER="<username>"



Those new rules take effect the next time a device is plugged in. It might therefore be necessary to unplug the device and plug it back into the computer. This is known to work on both Ubuntu Hardy Heron (8.04.x LTS) and Lucid Lynx (10.04.x LTS). Other versions of Ubuntu or other variants of GNU/linux might require different configurations.

(To check if the new rules worked, try the command 'adb devices' and you should get the phone's serial number. If you get '???????? no permissions', then try sudo service udev restart).

Final Checks

Before moving forward, verify the following two:

$ echo $USE_CCACHE

The above should return the number 1 (one).

$ echo $PATH

The above should return a string including ~/bin and your path to the ADT bundle.


If either command does not display the desired result:

  1. Restart your terminal. The modifications to system variables and the path are applied at the start of a terminal, so if you haven't restarted it in a while, do so.
  2. Make sure that the 'export USE_CCACHE=1' and path modifications mentioned earlier have been completed.