1 Rebuilding the Android emulator from sources 2 ============================================ 3 4 I. Getting the sources: 5 ----------------------- 6 7 At the moment, you'll need a full AOSP source checkout to rebuild the 8 emulator from sources. See the instructions at http://source.android.com on 9 how to download the platform sources. 10 11 The 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 22 II. Building: 23 ------------- 24 25 You can only build the emulator on Linux or Darwin. Windows binaries are 26 always generated on Linux, and actually run under Wine (more on this later). 27 28 There are currently two ways to build the emulator: 29 30 1) Using the standalone build-system: 31 32 As long as the directories listed in section I. exist, you can build the 33 emulator binaries from sources directly by using the android-rebuild.sh 34 script, i.e.: 35 36 cd $AOSP/external/qemu 37 ./android-rebuild.sh 38 39 This will build all related binaries, and run the small GoogleTest-based 40 unit test suite for your host system. 41 42 This places everything under the 'objs/' sub-directory, and you can launch 43 the emulator directly with something like: 44 45 export ANDROID_SDK_ROOT=/path/to/sdk 46 objs/emulator @<avd-name> [<other-options>...] 47 48 Use ./android-rebuild.sh --help for more details and command-line options. 49 50 51 2) Using the Android platform build: 52 53 If you have a full checkout of the AOSP source tree, the emulator will be 54 built as part of a regular "make" invokation, and the binaries placed under 55 out/host/<system>/bin/, allowing you to just run 'emulator' after the build. 56 For 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 64 Note that this scheme is _much_slower though, but once you have performed 65 a full build, you will be able to only rebuild the emulator quickly by 66 doing the following (after the commands above): 67 68 cd external/qemu 69 mm -j$NUM_CORES 70 71 The 'mm' command is a special function sourced into your environment by 72 envsetup.sh 73 74 Note: 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 77 In 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 83 With <cpu> being one of the CPU architectures supported by the 84 Android emulator (e.g. 'arm', 'x86' or 'mips'). 85 86 The 'emulator' executable is a very small program used to probe 87 the host system and the AVD you want to launch, in order to 88 invoke the appropriate 'real' emulator program. It also adjusts 89 library search paths to ensure that the emulator can load the 90 GPU emulation libraries from the right location. 91 92 Note that there are no emulator64-<cpu> executables generated on 93 Windows at the moment, due to issues with the mingw32-w64 cross-toolchains. 94 95 Define ANDROID_SDK_ROOT in your environment to point to your SDK installation 96 and be able to start AVDs with your freshly built emulator. 97 98 99 3) Building Windows emulator binaries: 100 101 Windows emulator binaries are always built on Linux, using a cross-toolchain, 102 there is no support to build the sources directly on Windows with MSys or 103 Cygwin. 104 105 Two 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 119 To build the Windows binaries, use the --mingw option, as in: 120 121 cd external/qemu 122 ./android-rebuild.sh --mingw 123 124 Again, all files are placed under objs/. 125 126 If you have Wine installed, you can launch objs/emulator.exe directly, but 127 you need to setup two environment variables first: 128 129 export ANDROID_SDK_ROOT=/path/to/sdk/install 130 export ANDROID_SDK_HOME=$HOME 131 132 The latter is required, otherwise the Windows binary will not find your AVDs 133 when running under Wine (which does special magic when important variable 134 from the environment that map to host file paths). 135 136 NOTE: 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 144 4) Rebuilding binaries for all host architectures at the same time: 145 146 A script under distrib/package-release.sh is provided to rebuild all 147 binaries from sources. By default, it will try to rebuild for Linux and 148 Windows, but if you have ssh access to a Darwin machine with the command-line 149 XCode 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 156 You can enable this by using the --darwin-ssh=<host> option, or by setting 157 the ANDROID_EMULATOR_DARWIN_SSH variable to the hostname. 158 159 In case of success, this creates 4 tarballs under /tmp: One for the set of 160 sources used to perform the build, and 3 others for the 161 Linux / Darwin / Windows packages. 162 163 These packages place the binaries under a top-level tools/ directory, so you 164 can 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
