src/source/building.md

# Building the System #

The basic sequence of build commands is as follows:

## Initialize ##

Initialize the environment with the `envsetup.sh` script. Note
that replacing "source" with a single dot saves a few characters,
and the short form is more commonly used in documentation.

    $ source build/envsetup.sh

or
    
    $ . build/envsetup.sh

## Choose a Target ##

Choose which target to build with `lunch`.  The exact configuration can be passed as
an argument, e.g. 
    
    $ lunch full-eng

Common targets include
    
- **full-eng**: emulator build with all debugging enabled
- **full_passion-userdebug**: passion (Nexus One) build with minimal debugging 
- **full_crespo-userdebug**: crespo (Nexus S) build with minimal debugging. 

If run with no arguments `lunch` will prompt you to choose a target from the menu. 

All build targets take the form DEVICE-BUILDTYPE, where the DEVICE is a codename 
referring to the particular hardware:

Codename   | Device
-----------|-----------
passion    | Nexus One
crespo     | Nexus S
voles      | Droid
opal       | myTouch/Sapphire

and the BUILDTYPE is one of the following:

Buildtype   | Use
------------|--------------------------------------
user        | limited access; suited for production
userdebug   | like "user" but with `su` access; preferred for debugging
eng         | unrestricted access

## Build the Code ##

Build everything with `make`. GNU make can handle parallel
tasks with a `-jN` argument, and it's common to use a number of
tasks N that's between 1 and 2 times the number of hardware
threads on the computer being used for the build. E.g. on a
dual-E5520 machine (2 CPUs, 4 cores per CPU, 2 threads per core),
the fastest builds are made with commands between `make -j16` and
`make -j32`.

    $ make -j4

## Run It! ##

You can either run your build on an emulator or flash it on a device. Please note that you have already selected your build target with `lunch`, and it is unlikely at best to run on a different target than it was built for.

### Flash a Device ###

To flash a device, you will need to use `fastboot`, which should be included in your path after a successful build. Place the device in fastboot mode either manually by holding the appropriate key combination at boot, or from the shell with

    $ adb reboot bootloader

Once the device is in fastboot mode, run 

    $ fastboot flashall -w

The `-w` option wipes the `/data` partition on the device; this is useful for your first time flashing a particular device, but is otherwise unnecessary.

### Emulate an Android Device ###

The emulator is added to your path automatically by the build process. To run the emulator, type

    $ emulator


# Troubleshooting Common Build Errors #

## Wrong Java Version ##

If you are attempting to build froyo or earlier with Java 1.6, or gingerbread or later
with Java 1.5, `make` will abort with a message such as

    ************************************************************
    You are attempting to build with the incorrect version
    of java.
 
    Your version is: WRONG_VERSION.
    The correct version is: RIGHT_VERSION.
 
    Please follow the machine setup instructions at
        http://source.android.com/download
    ************************************************************

This may be caused by

- failing to install the correct JDK as specified on the [Initializing](initializing.html) page.  Building Android requires Sun JDK 5 or 6 depending on which release you are building.  

- another JDK that you previously installed appearing in your path.  You can remove the offending JDK from your path with:

        $ export PATH=${PATH/\/path\/to\/jdk\/dir:/}

## Python Version 3 ##

Repo is built on particular functionality from Python 2.x and is unfortunately incompatible with Python 3.  In order to use repo, please install Python 2.x:

    $ apt-get install python

## Gmake Version 3.82 ##

There is a bug in `make` version 3.82 on Mac OS that prevents building Android. 

TODO: what the error looks like with GNU make 3.82 on older builds that don't explicitly detect it.

Follow the instructions on the [Initializing](initializing.html) page for reverting GNU make from 3.82 to 3.81.

## Case Insensitive Filesystem ##

If you are building on an HFS filesystem on Mac OS X, you may encounter an error such as

    ************************************************************
    You are building on a case-insensitive filesystem.
    Please move your source tree to a case-sensitive filesystem.
    ************************************************************

Please follow the instructions on the [Initializing](initializing.html) page for creating a case-sensitive disk image.

## No USB Permission ##

On most Linux systems, unprivileged users cannot access USB ports by default. 

TODO: what error will occur?

Follow the instructions on the [Initializing](initializing.html) page for configuring USB access.  

If adb was already running and cannot connect to the device after
getting those rules set up, it can be killed with `adb kill-server`.
That will cause adb to restart with the new configuration.