docs/BUILDING.TXT

Rebuilding the Android emulator from sources
============================================

I. Getting the sources:
-----------------------

At the moment, you'll need a full AOSP source checkout to rebuild the
emulator from sources. See the instructions at http://source.android.com on
how to download the platform sources.

The following directories will be relevant:

  $AOSP/external/qemu        -> The emulator itself.
  $AOSP/external/getst       -> The GoogleTest sources.
  $AOSP/sdk/emulator/opengl  -> Host GPU emulation libraries.

  $AOSP/prebuilts/tools/gcc-sdk           -> host toolchains for SDK tools.
  $AOSP/prebuilts/gcc/linux-x86/host/
  $AOSP/prebuilts/gcc/darwin-x86/host/


II. Building:
-------------

You can only build the emulator on Linux or Darwin. Windows binaries are
always generated on Linux, and actually run under Wine (more on this later).

There are currently two ways to build the emulator:

1) Using the standalone build-system:

As long as the directories listed in section I. exist, you can build the
emulator binaries from sources directly by using the android-rebuild.sh
script, i.e.:

  cd $AOSP/external/qemu
  ./android-rebuild.sh

This will build all related binaries, and run the small GoogleTest-based
unit test suite for your host system.

This places everything under the 'objs/' sub-directory, and you can launch
the emulator directly with something like:

  export ANDROID_SDK_ROOT=/path/to/sdk
  objs/emulator @<avd-name>  [<other-options>...]

Use ./android-rebuild.sh --help for more details and command-line options.


2) Using the Android platform build:

If you have a full checkout of the AOSP source tree, the emulator will be
built as part of a regular "make" invokation, and the binaries placed under
out/host/<system>/bin/, allowing you to just run 'emulator' after the build.
For example, for an ARM-based SDK system image build:

  cd $AOSP
  . build/envsetup.sh
  lunch sdk-eng
  make -j$NUM_CORES
  emulator

Note that this scheme is _much_slower though, but once you have performed
a full build, you will be able to only rebuild the emulator quickly by
doing the following (after the commands above):

  cd external/qemu
  mm -j$NUM_CORES

The 'mm' command is a special function sourced into your environment by
envsetup.sh

Note: The default SDK system image maps to an ARMv7-based virtual CPU,
      use 'sdk_x86-eng' or 'sdk_mips-eng' to build x86 or MIPS based ones.

In all cases, several binaries will be generated:

    emulator         -> 32-bit launcher program.
    emulator-<cpu>   -> 32-bit emulator for Android <cpu> images.
    emulator64-<cpu> -> 64-bit emulator for Android <cpu> images.

With <cpu> being one of the CPU architectures supported by the
Android emulator (e.g. 'arm', 'x86' or 'mips').

The 'emulator' executable is a very small program used to probe
the host system and the AVD you want to launch, in order to
invoke the appropriate 'real' emulator program. It also adjusts
library search paths to ensure that the emulator can load the
GPU emulation libraries from the right location.

Note that there are no emulator64-<cpu> executables generated on
Windows at the moment, due to issues with the mingw32-w64 cross-toolchains.

Define ANDROID_SDK_ROOT in your environment to point to your SDK installation
and be able to start AVDs with your freshly built emulator.


3) Building Windows emulator binaries:

Windows emulator binaries are always built on Linux, using a cross-toolchain,
there is no support to build the sources directly on Windows with MSys or
Cygwin.

Two cross-toolchains are supported:

  1) The Ubuntu 12.04 "mingw32" toolchain, which can only generate Win32
     executables.

     Note that the "mingw64" toolchain in 12.04 is broken, and conflicts
     with the mingw32 anyway, so never try to use / install it.

  2) Our own custom w64-based toolchain (x86_64-w64-mingw32), which can
     generate both Win32 and Win64 executables. You just need to have
     x86_64-w64-mingw32-gcc in your PATH for it to be used.

     [WARNING: Currently only works in aosp/master branch, not aosp/idea133]

To build the Windows binaries, use the --mingw option, as in:

  cd external/qemu
  ./android-rebuild.sh --mingw

Again, all files are placed under objs/.

If you have Wine installed, you can launch objs/emulator.exe directly, but
you need to setup two environment variables first:

  export ANDROID_SDK_ROOT=/path/to/sdk/install
  export ANDROID_SDK_HOME=$HOME

The latter is required, otherwise the Windows binary will not find your AVDs
when running under Wine (which does special magic when important variable
from the environment that map to host file paths).

NOTE: Performance of Windows binaries under Wine is currently pretty bad,
      unless you add '-qemu -clock dynticks' to your command-line.

      This doesn't affect the exact same binary running under a real Windows
      installation. For more context, see:
              https://android-review.googlesource.com/#/c/82661/


4) Rebuilding binaries for all host architectures at the same time:

A script under distrib/package-release.sh is provided to rebuild all
binaries from sources. By default, it will try to rebuild for Linux and
Windows, but if you have ssh access to a Darwin machine with the command-line
XCode tools installed, it will also automatically:

  - Pack the sources into a tarball
  - Upload it through ssh to a temporary directory on the machine.
  - Perform a Darwin build there, and run GTest-based unit tests.
  - Retrieve the final binaries in case of success.

You can enable this by using the --darwin-ssh=<host> option, or by setting
the ANDROID_EMULATOR_DARWIN_SSH variable to the hostname.

In case of success, this creates 4 tarballs under /tmp: One for the set of
sources used to perform the build, and 3 others for the
Linux / Darwin / Windows packages.

These packages place the binaries under a top-level tools/ directory, so you
can uncompress them directly at the top of an existing SDK installation
(in the case where you want to update the emulator binaries there).