---
layout: doc
title: "Set up your environment - Android"
---

These instructions explain how to set up Cobalt for your workstation and Android
device. The package being built here is referred to as CoAT (Cobalt on Android TV).

## Preliminary Setup

1.  Download 'depot_tools', which is used to build the Cobalt code. An easy
    option is to put them in `~/depot_tools`. Clone the tools, by running the
    following command:

    ```
    cd ~/
    git clone https://cobalt.googlesource.com/depot_tools
    ```

1.  Add your 'depot_tools' directory to the end of your PATH variable. We
    recommend adding something like this to your `.bashrc` or `.profile` file:

    ```
    PATH=${PATH}:/path/to/depot_tools
    ```

1.  Additional build dependencies may need to be installed:
    ```
    sudo apt-get install python python-pip
    ```

    If `python-pip` is not available via your package mangaer, you can install `pip` following [recommended instructions](https://pip.pypa.io/en/stable/installing/) from the official Python guide.

    There are also some Python module requirements:

    ```
    python -m pip install requests
    ```

1.  Install ccache to support build acceleration. ccache is automatically used
    when available, otherwise defaults to unaccelerated building:

    ```
    $ sudo apt-get install ccache
    ```

    We recommend adjusting the cache size as needed to increase cache hits:

    ```
    $ ccache --max-size=20G
    ```

1.  Download and install [Android Studio](https://developer.android.com/studio/).
1.  Run `cobalt/build/gyp_cobalt android-x86` to configure the Cobalt build,
    which also installs the SDK and NDK. (This step will have to be repeated
    with 'android-arm' or 'android-arm64' to target those architectures.) The
    SDK and NDK will be downloaded and installed into a `starboard-toolchains`
    directory as needed. If prompted, read and accept the license agreement to
    proceed forward.

    **Note:** If you have trouble building with an error referencing the
    `debug.keystore` you may need to set one up on your system:

    ```
    keytool -genkey -v -keystore ~/.android/debug.keystore -storepass android -alias androiddebugkey -keypass android -keyalg RSA -keysize 2048 -validity 10000
    ```

## Setup your device

Configure your device to be in developer mode:

1.  From `Settings`, in the `Device` row, select `About`.
1.  Scroll down to and click on `Build` several times until a toast appears with
    the message, "You are now a developer."
1.  In the newly added "developer options" settings menu, make sure USB
    debugging is enabled.

## Setup your workstation environment

For manually installing Android Studio and the SDK.

**Note:** Instructions moving forward are assuming a Linux environment.

1.  Complete the Preliminary Setup above.
1.  Launch Android Studio.
1.  Android Studio may still prompt to install an SDK if this is the very first
    time you've run it.
Go ahead and click 'yes' to open the SDK manager to install the following:
    *   Edit "Android SDK location" and set the path to:
    `$HOME/starboard-toolchains/AndroidSdk`
      *  NOTE: We use the same SDK for the IDE and the gyp/ninja build. This
         directory will already exist since you've already run gyp_cobalt for an
         android target, so you'll see a warning in the setup wizard that an SDK
         was detected, which is okay.
          * The path may also be `$HOME/cobalt-toolchains/AndroidSdk` if you
            previously had an older environment configured on your machine -
            this is okay.
        *  Select both `Android SDK` and `Android SDK Platform` (whatever
           current version is presented should be fine)
    *   On the `SDK Platforms` tab select:
        *  Android API 28 (or whatever was already installed by default)
    *   On the "SDK Tools" tab select
(most of these should already be installed since you already ran gyp):
        1.  Android SDK Build-Tools (e.g. 28.0.3)
        1.  CMake
        1.  LLDB
        1.  Android Emulator
        1.  Android SDK Platform-Tools
        1.  Android SDK Tools
        1.  NDK
        1.  Support Repository > Android Support Repository
        1.  Support Repository > Google Repository
1.  At the welcome screen, choose to open an existing Android Studio project,
    and choose the project in your Cobalt repo at `starboard/android/apk` (just
    select the directory). This is "coat" (Cobalt On Android TV).
    *   NOTE: Do not let it update the 'Android Gradle Plugin' if it prompts for
        that, use the 'Don't remind me again' button. If you inadvertently let
        it upgrade, you can just revert the change to `build.gradle` in your git
        repo.
1.  You may see a popup "Unregistered VCS roots detected" indicating that it has
    detected the cobalt git repo. If you want to use git integration in
    Android Studio, you can add the roots, or if not then choose to ignore them.
1.  If you didn't already get prompted to install the SDK, do it now by going to
    Tools -> SDK Manager (or
    <img src="/images/android-sdk-manager-icon.png" style="display:inline;"></img>
    ) on the toolbar) and making the same choices as shown in step 4.
1.  Make a new virtual device (= emulator) via
    Tools -> AVD Manager (or
    <img src="/images/android-avd-manager-icon.png" style="display: inline;"></img>
    on the toolbar).
      *   Category: TV -> Android TV (720p)
      *   System image: Pie (API 28) x86 (you'll have to download the image)
          (The code should work on any API 21+, but there's a bug in the
          emulator preventing API 21 from working, but it does work on API 21
          hardware)
      *   You may be prompted to install some Intel virtualization drivers
          and/or change some BIOS settings to enable it, which will require you
          to reboot your machine.
1.  Run this AVD device. You can keep it running. Remember to restart it if your
    machine reboots. (Or you can start it when prompted for the target device if
    launching the app from Android Studio.)

## Basic Build, Install, and Run (command-line based)

1.  Complete the Preliminary Setup above
1.  Generate the cobalt.apk by building the "cobalt_deploy" target

    ```
    ninja -C out/android-x86_gold cobalt_deploy
    ```

    Output can be found in the corresponding `out/android-x86_gold` directory.

    **Note:** If you have trouble building with an error referencing the
    `debug.keystore` you may need to set one up on your system:

    ```
    keytool -genkey -v -keystore ~/.android/debug.keystore -storepass android -alias androiddebugkey -keypass android -keyalg RSA -keysize 2048 -validity 10000
    ```

1.  Install the resulting APK into your test device with adb:

    ```
    adb install out/android-x86_gold/cobalt.apk
    ```

1.  Start the application with:

    ```
    adb shell am start dev.cobalt.coat/dev.cobalt.app.MainActivity
    ```

1.  For command line parameters use the `--esa` flag to specify the "args" array
    as comma-separated values (with characters backslash-escaped as needed to
    make it through both the shell on your workstation and the shell on the
    device), e.g.:

    ```
    adb shell am start --esa args --flag_arg,--value_arg=something dev.cobalt.coat
    ```

1.  To monitor log output, watch logcat in another shell with a filter for
    starboard messages:

    ```
    adb logcat -s starboard:*
    ```

1.  To kill any existing running application process (even if it's no longer the
    active app) use:

    ```
    adb shell am force-stop dev.cobalt.coat
    ```

## Building/running/debugging (Android Studio IDE)

1.  Manually run `cobalt/build/gyp_cobalt android-x86` in a shell. (You should
    do this after each time you sync your repo)
1.  From the initial setup above, you should have opened the Android Studio
    project checked in at `starboard/android/apk`.
1.  In the sidebar on the left, you should see `app` appear as bolded top-level
    item.  If you don't see this, restart Android Studio.
1.  If you didn't install your Cobalt depot_tools in the standard location
    (`$HOME/depot_tools`), then make `starboard/android/apk/app/.cobaltrc` and
    set the `DEPOT_TOOLS` envvar to the path to where you installed them (or
    make a symlink in the standard location to where you have them).
1.  To run the app and attach the debugger: Run -> Debug 'app' (or
    <img src="/images/android-debug-icon.png" style="display: inline;"></img>
    in the toolbar)
1.  If it's taking awhile, it's probably the ninja build. You can see that it is
    still processing by looking for a rotating spinner labeled "Gradle Build
    Running" on the bottom bar.

    **Note:** If you have trouble building with an error referencing the
    `debug.keystore` you may need to set one up on your system:

    ```
    keytool -genkey -v -keystore ~/.android/debug.keystore -storepass android -alias androiddebugkey -keypass android -keyalg RSA -keysize 2048 -validity 10000
    ```

1.  To add command line parameters add `--esa` to specify the "args" array as
    comma-separated values (with characters like '&' backslash-escaped to make
    it through the launch command) under:

    Run -> Edit Configurations… -> "app" -> General -> Launch Options -> Launch Flags

    e.g. To run with a different URL: `--esa args --url=<DIFFERENT_URL>`
1.  To monitor log output, see the `Logcat` on the bottom-left of the IDE. You
    can enter "starboard" in the search bubble to filter the output.
1.  To kill the app go to Run -> Stop, or click the red square stop button
    either on the top toolbar, or in the debugger on the bottom-left of the IDE.
1.  To set breakpoints in native code, just open the relevant source file with
    File -> Open… (sorry, files outside the apk project can't appear in the
    Project panel of the IDE) and click in the gutter of the relevant line.
    (Once you have one C++ file open, the path breadcrumbs at the top are useful
    to open other nearby files.)


## Running Tests

The test target itself (e.g. nplb) just builds an .so file (e.g. libnplb.so). To
run that on a device, it needs to be packaged into an APK, which is done by the
associated "deploy" target (e.g. nplb_deploy). The Starboard test runner does
all this for you, so just use that to build and run tests. For example, to
build and run "devel" NPLB on an ARM64 device, from the top 'src' directory:

```
starboard/tools/testing/test_runner.py -p android-arm64 -c devel -b -r -t nplb
```

If you want to debug a test, you can run it from Android Studio. Edit
`build.gradle` in the 'app' module (not to the one in the top 'apk' module) to
change `DEFAULT_COBALT_TARGET` to be the name of the test you want to debug
instead of 'cobalt'. Then you can set breakpoints, etc. in the test the same as
when debugging Cobalt.

## Removing the Cobalt Android Environment

1.  Unset ANDROID_HOME and or ANDROID_NDK_HOME in your shell and in .bashrc
1.  Delete the SDK:

    ```
    rm -rf ~/starboard-toolchains/AndroidSdk
    ```

1.  Delete NDK toolchains:

    ```
    rm -rf  ~/starboard-toolchains/android*
    ```

1.  Delete cached Android files:

    ```
    rm -rf ~/.android
    ```

    **NOTE:** Removing this directory will remove all signing keys even for
    different projects, so only delete this if you truly want to remove the
    entire Cobalt and Android Studio environment.