Docs: more docs for working with the emulator
This adds miscellaneous tips for working with the emulator:
* Explain which image to choose, and what "Google APIs" really means
(this especially matters for WebView development)
* Tips for running from CLI (headless, writable system)
* Change install instructions for `virtualgl`, point Googlers toward
relevant documentation.
* Formatting, restructuring docs
[email protected]
Bug: 918221
Test: Upload to gerrit > open file > click "gitiles"
Change-Id: Ie634516d1a19f9653e21a2e0586410618b7eefb7
Reviewed-on: https://chromium-review.googlesource.com/c/1432837
Reviewed-by: Andrew Grieve <[email protected]>
Commit-Queue: Nate Fischer <[email protected]>
Cr-Commit-Position: refs/heads/master@{#625791}diff --git a/docs/android_emulator.md b/docs/android_emulator.md
index e4de232..28fb84bb 100644
--- a/docs/android_emulator.md
+++ b/docs/android_emulator.md
@@ -1,10 +1,10 @@
# Using an Android Emulator
Always use x86 emulators. Although arm emulators exist, they are so slow that
-they are not worth your time.
+they are not worth your time.
## Building for Emulation
You need to target the correct architecture via GN args:
-```
+```gn
target_cpu = "x86"
```
@@ -20,14 +20,29 @@
* Emulator configs and data partition images are stored within
`~/.android/avd/`.
-When creating images:
- * Choose a skin with a small screen for better performance (unless you care
- about testing large screens).
- * Under "Advanced":
- * Set internal storage to 4000MB (component builds are really big).
- * Set SD card to 1000MB (our tests push a lot of files to /sdcard).
+### Choosing a Skin
+Choose a skin with a small screen for better performance (unless you care about
+testing large screens).
-Known issues:
+### Choosing an Image
+Android Studio's image labels roughly translate to the following:
+
+| AVD "Target" | GMS? | Build Properties |
+| --- | --- | --- |
+| Google Play | This has GMS | `user`/`release-keys` |
+| Google APIs | This has GMS | `userdebug`/`dev-keys` |
+| No label | AOSP image, does not have GMS | `eng`/`test-keys` |
+
+*** promo
+If you're not sure which to use, **choose Google APIs**.
+***
+
+### Configuration
+"Show Advanced Settings" > scroll down:
+* Set internal storage to 4000MB (component builds are really big).
+* Set SD card to 1000MB (our tests push a lot of files to /sdcard).
+
+### Known Issues
* Our test & installer scripts do not work with pre-MR1 Jelly Bean.
* Component builds do not work on pre-KitKat (due to the OS having a max
number of shared libraries).
@@ -42,7 +57,7 @@
than use the UI to create additional avds, you can clone an existing one via:
```shell
-tools/android/emulator/clone_avd.py \
+$ tools/android/emulator/clone_avd.py \
--source-ini ~/.android/avd/EMULATOR_ID.ini \
--dest-ini ~/.android/avd/EMULATOR_ID_CLONED.ini \
--display-name "Cloned Emulator"
@@ -51,12 +66,36 @@
## Starting an Emulator from the Command Line
Refer to: https://developer.android.com/studio/run/emulator-commandline.html.
-Note: Ctrl-C will gracefully close an emulator.
+*** promo
+Ctrl-C will gracefully close an emulator.
+***
-If running under remote desktop:
+### Basic Command Line Use
+```shell
+$ ~/Android/Sdk/emulator/emulator @EMULATOR_ID
```
-sudo apt-get install virtualgl
-vglrun ~/Android/Sdk/tools/emulator @EMULATOR_ID
+
+### Running a Headless Emulator
+You can run an emulator without creating a window on your desktop (useful for
+`ssh`):
+```shell
+$ sudo apt-get install xvfb-run
+$ xvfb-run ~/Android/Sdk/emulator/emulator -gpu off @EMULATOR_ID
+```
+
+### Writable system partition
+Unlike physical devices, an emulator's `/system` partition cannot be modified by
+default (even on rooted devices). If you need to do so (such as to remove a
+system app), you can start your emulator like so:
+```shell
+$ ~/Android/Sdk/emulator/emulator -writable-system @EMULATOR_ID
+```
+
+### Remote Desktop
+For better graphics performance, use virtualgl (Googlers, see
+http://go/virtualgl):
+```shell
+$ vglrun ~/Android/Sdk/emulator/emulator @EMULATOR_ID
```
## Using an Emulator
