David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 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. |
David 'Digit' Turner | d3366f1 | 2014-05-07 10:47:47 +0200 | [diff] [blame] | 14 | $AOSP/external/getst -> The GoogleTest sources. |
David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 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 | |
David 'Digit' Turner | d3366f1 | 2014-05-07 10:47:47 +0200 | [diff] [blame] | 22 | II. Building: |
| 23 | ------------- |
David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 24 | |
David 'Digit' Turner | d3366f1 | 2014-05-07 10:47:47 +0200 | [diff] [blame] | 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). |
David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 27 | |
David 'Digit' Turner | d3366f1 | 2014-05-07 10:47:47 +0200 | [diff] [blame] | 28 | There are currently two ways to build the emulator: |
David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 29 | |
David 'Digit' Turner | d3366f1 | 2014-05-07 10:47:47 +0200 | [diff] [blame] | 30 | 1) Using the standalone build-system: |
David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 31 | |
David 'Digit' Turner | d3366f1 | 2014-05-07 10:47:47 +0200 | [diff] [blame] | 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.: |
David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 35 | |
David 'Digit' Turner | d3366f1 | 2014-05-07 10:47:47 +0200 | [diff] [blame] | 36 | cd $AOSP/external/qemu |
| 37 | ./android-rebuild.sh |
David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 38 | |
David 'Digit' Turner | d3366f1 | 2014-05-07 10:47:47 +0200 | [diff] [blame] | 39 | This will build all related binaries, and run the small GoogleTest-based |
| 40 | unit test suite for your host system. |
David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 41 | |
David 'Digit' Turner | d3366f1 | 2014-05-07 10:47:47 +0200 | [diff] [blame] | 42 | This places everything under the 'objs/' sub-directory, and you can launch |
| 43 | the emulator directly with something like: |
David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 44 | |
| 45 | export ANDROID_SDK_ROOT=/path/to/sdk |
David 'Digit' Turner | d3366f1 | 2014-05-07 10:47:47 +0200 | [diff] [blame] | 46 | objs/emulator @<avd-name> [<other-options>...] |
| 47 | |
| 48 | Use ./android-rebuild.sh --help for more details and command-line options. |
David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 49 | |
| 50 | |
David 'Digit' Turner | d3366f1 | 2014-05-07 10:47:47 +0200 | [diff] [blame] | 51 | 2) Using the Android platform build: |
David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 52 | |
David 'Digit' Turner | d3366f1 | 2014-05-07 10:47:47 +0200 | [diff] [blame] | 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: |
David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 57 | |
David 'Digit' Turner | d3366f1 | 2014-05-07 10:47:47 +0200 | [diff] [blame] | 58 | cd $AOSP |
| 59 | . build/envsetup.sh |
| 60 | lunch sdk-eng |
| 61 | make -j$NUM_CORES |
| 62 | emulator |
David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 63 | |
David 'Digit' Turner | d3366f1 | 2014-05-07 10:47:47 +0200 | [diff] [blame] | 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): |
David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 67 | |
David 'Digit' Turner | d3366f1 | 2014-05-07 10:47:47 +0200 | [diff] [blame] | 68 | cd external/qemu |
| 69 | mm -j$NUM_CORES |
David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 70 | |
David 'Digit' Turner | d3366f1 | 2014-05-07 10:47:47 +0200 | [diff] [blame] | 71 | The 'mm' command is a special function sourced into your environment by |
| 72 | envsetup.sh |
David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 73 | |
David 'Digit' Turner | d3366f1 | 2014-05-07 10:47:47 +0200 | [diff] [blame] | 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. |
David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 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. |
David 'Digit' Turner | d3366f1 | 2014-05-07 10:47:47 +0200 | [diff] [blame] | 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). |