android_webview/docs/device-setup.md

# Device Setup for WebView development

[TOC]

As WebView is an Android system component (rather than just an app), WebView
imposes additional requirements on the developer workflow. In particular,
WebView requires a physical device or emulator with a `userdebug` or `eng`
Android image. WebView doesn't support development on `user` builds.

To build WebView, or [run WebView's automated tests](./test-instructions.md),
you'll need to set up either an emulator or a physical device.

## I have a device or emulator. Will it work for development?

You can check which Android image you have on your device with the following:

```sh
# If you don't have `adb` in your path, you can source this file to use
# the copy from chromium's Android SDK.
$ source build/android/envsetup.sh

# If this outputs "userdebug" or "eng" then you're OK! If this outputs "user"
# then you must reflash your physical device or configure a new emulator
# following this guide.
$ adb shell getprop ro.build.type
userdebug

# The API level needs to be 29 or higher:
$ adb shell getprop ro.build.version.sdk
29
```

## Emulator (easy way)

*** promo
Unless you have a hardware-specific bug, or need to use a pre-release Android
version, a physical device is usually unnecessary. An `x86` emulator should be
easier to setup.
***

You can generally follow chromium's [Android
emulator](/docs/android_emulator.md) instructions. You should choose a **Google
APIs** image. The AOSP-based image will also work, but imposes additional
developer hurdles. Note that you shouldn't use a **Google Play** image for
development purposes because they are `user` builds, see [Why won't a user
image work](#why-won_t-a-user-image-work) below.

Choose an emulator image which is Android 10 (SDK 29) or higher.

## Physical device

### Flash a prebuilt image

Googlers can consult internal instructions
[here](http://go/clank-webview/device_setup.md).

External contributors can flash a prebuilt `userdebug` image (based off
aosp-main) onto a Pixel device with [Android Flash
Tool](https://flash.android.com/welcome?continue=%2Fcustom). This requires a
browser capable of WebUSB (we recommend the latest Google Chrome stable
release).

Choose an build image which is Android 10 (SDK 29) or higher.

### Building AOSP yourself (hard way)

*** note
This takes significantly longer than the two previous methods, so please
strongly consider one of the above first.
***

**Prerequisite:** a machine capable of [building
Android](https://source.android.com/source/building.html).

Clone an AOSP checkout, picking a branch supported for your device (you'll need
a branch above 10.0.0) from the [list of
branches](https://source.android.com/setup/start/build-numbers.html#source-code-tags-and-builds):

```shell
mkdir aosp/ && cd aosp/ && \
  repo init -u 'https://android.googlesource.com/platform/manifest' -b android-<VERSION> && \
  repo sync -c -j<number>
```

You can obtain binary drivers for Nexus/Pixel devices
[here](https://developers.google.com/android/drivers). Drivers should match your
device and branch. Extract and run the shell script:

```shell
# Change the filenames to match your device/branch (this uses "crosshatch" as an
# example)
tar -xvzf /path/to/qcom-crosshatch-pd1a.180720.030-bf86f269.tgz
./extract-qcom-crosshatch.sh # Extracts to the vendor/ folder
```

You can build AOSP and flash your device with:

```shell
source build/envsetup.sh
device="crosshatch" # Change this depending on your device hardware
lunch aosp_${device}-userdebug
make -j<number>

# Flash to device
adb reboot bootloader
fastboot -w flashall
```

For more information, please defer to [official
instructions](https://source.android.com/setup/build/downloading).

## Why won't a user image work?

`user` images have all of Android's security features turned on (and they can't
be disabled). In particular, you won't be able to install a locally built
WebView:

* Most `user` images are `release-keys` signed, which means local WebView builds
  can't install over the preinstalled standalone WebView.
* `user` images have extra validity checks for the WebView provider package
  which pose as an obstacle when loading your own locally compiled WebView for
  debugging purposes.

Both of the above are important security features: these protect users from
running malware in the context of WebView (which runs inside the context of
apps). Unfortunately, these features break debugging and development so the
features are disabled for engineering OS images.