1Rebuilding the Android emulator from sources 2============================================ 3 4I. Getting the sources: 5----------------------- 6 7At the moment, you'll need a full AOSP source checkout to rebuild the 8emulator from sources. See the instructions at http://source.android.com on 9how to download the platform sources. 10 11The following directories will be relevant: 12 13 $AOSP/external/qemu -> The emulator itself. 14 $AOSP/external/getst -> The GoogleTest sources. 15 $AOSP/sdk/emulator/opengl -> Host GPU emulation libraries. 16 17 $AOSP/prebuilts/tools/gcc-sdk -> host toolchains for SDK tools. 18 $AOSP/prebuilts/gcc/linux-x86/host/ 19 $AOSP/prebuilts/gcc/darwin-x86/host/ 20 21 22II. Building: 23------------- 24 25You can only build the emulator on Linux or Darwin. Windows binaries are 26always generated on Linux, and actually run under Wine (more on this later). 27 28There are currently two ways to build the emulator: 29 301) Using the standalone build-system: 31 32As long as the directories listed in section I. exist, you can build the 33emulator binaries from sources directly by using the android-rebuild.sh 34script, i.e.: 35 36 cd $AOSP/external/qemu 37 ./android-rebuild.sh 38 39This will build all related binaries, and run the small GoogleTest-based 40unit test suite for your host system. 41 42This places everything under the 'objs/' sub-directory, and you can launch 43the emulator directly with something like: 44 45 export ANDROID_SDK_ROOT=/path/to/sdk 46 objs/emulator @<avd-name> [<other-options>...] 47 48Use ./android-rebuild.sh --help for more details and command-line options. 49 50 512) Using the Android platform build: 52 53If you have a full checkout of the AOSP source tree, the emulator will be 54built as part of a regular "make" invokation, and the binaries placed under 55out/host/<system>/bin/, allowing you to just run 'emulator' after the build. 56For example, for an ARM-based SDK system image build: 57 58 cd $AOSP 59 . build/envsetup.sh 60 lunch sdk-eng 61 make -j$NUM_CORES 62 emulator 63 64Note that this scheme is _much_slower though, but once you have performed 65a full build, you will be able to only rebuild the emulator quickly by 66doing the following (after the commands above): 67 68 cd external/qemu 69 mm -j$NUM_CORES 70 71The 'mm' command is a special function sourced into your environment by 72envsetup.sh 73 74Note: The default SDK system image maps to an ARMv7-based virtual CPU, 75 use 'sdk_x86-eng' or 'sdk_mips-eng' to build x86 or MIPS based ones. 76 77In all cases, several binaries will be generated: 78 79 emulator -> 32-bit launcher program. 80 emulator-<cpu> -> 32-bit emulator for Android <cpu> images. 81 emulator64-<cpu> -> 64-bit emulator for Android <cpu> images. 82 83With <cpu> being one of the CPU architectures supported by the 84Android emulator (e.g. 'arm', 'x86' or 'mips'). 85 86The 'emulator' executable is a very small program used to probe 87the host system and the AVD you want to launch, in order to 88invoke the appropriate 'real' emulator program. It also adjusts 89library search paths to ensure that the emulator can load the 90GPU emulation libraries from the right location. 91 92Note that there are no emulator64-<cpu> executables generated on 93Windows at the moment, due to issues with the mingw32-w64 cross-toolchains. 94 95Define ANDROID_SDK_ROOT in your environment to point to your SDK installation 96and be able to start AVDs with your freshly built emulator. 97 98 993) Building Windows emulator binaries: 100 101Windows emulator binaries are always built on Linux, using a cross-toolchain, 102there is no support to build the sources directly on Windows with MSys or 103Cygwin. 104 105Two cross-toolchains are supported: 106 107 1) The Ubuntu 12.04 "mingw32" toolchain, which can only generate Win32 108 executables. 109 110 Note that the "mingw64" toolchain in 12.04 is broken, and conflicts 111 with the mingw32 anyway, so never try to use / install it. 112 113 2) Our own custom w64-based toolchain (x86_64-w64-mingw32), which can 114 generate both Win32 and Win64 executables. You just need to have 115 x86_64-w64-mingw32-gcc in your PATH for it to be used. 116 117 [WARNING: Currently only works in aosp/master branch, not aosp/idea133] 118 119To build the Windows binaries, use the --mingw option, as in: 120 121 cd external/qemu 122 ./android-rebuild.sh --mingw 123 124Again, all files are placed under objs/. 125 126If you have Wine installed, you can launch objs/emulator.exe directly, but 127you need to setup two environment variables first: 128 129 export ANDROID_SDK_ROOT=/path/to/sdk/install 130 export ANDROID_SDK_HOME=$HOME 131 132The latter is required, otherwise the Windows binary will not find your AVDs 133when running under Wine (which does special magic when important variable 134from the environment that map to host file paths). 135 136NOTE: Performance of Windows binaries under Wine is currently pretty bad, 137 unless you add '-qemu -clock dynticks' to your command-line. 138 139 This doesn't affect the exact same binary running under a real Windows 140 installation. For more context, see: 141 https://android-review.googlesource.com/#/c/82661/ 142 143 1444) Rebuilding binaries for all host architectures at the same time: 145 146A script under distrib/package-release.sh is provided to rebuild all 147binaries from sources. By default, it will try to rebuild for Linux and 148Windows, but if you have ssh access to a Darwin machine with the command-line 149XCode tools installed, it will also automatically: 150 151 - Pack the sources into a tarball 152 - Upload it through ssh to a temporary directory on the machine. 153 - Perform a Darwin build there, and run GTest-based unit tests. 154 - Retrieve the final binaries in case of success. 155 156You can enable this by using the --darwin-ssh=<host> option, or by setting 157the ANDROID_EMULATOR_DARWIN_SSH variable to the hostname. 158 159In case of success, this creates 4 tarballs under /tmp: One for the set of 160sources used to perform the build, and 3 others for the 161Linux / Darwin / Windows packages. 162 163These packages place the binaries under a top-level tools/ directory, so you 164can uncompress them directly at the top of an existing SDK installation 165(in the case where you want to update the emulator binaries there). 166