Set up your environment - AOSP

Page Summary

• This document guides you through building Cobalt with evergreen enabled and running the API on an Android device, after first completing the workstation and developer tool setups.

• The process involves downloading the source code, setting up the build environment, downloading the Starboard toolchain and Android SDK, and installing necessary Linux packages.

• You must create output directories for evergreen, select and download pre-built Cobalt binaries from GitHub, and then copy the files to the appropriate directories.

• The instructions provide steps to compile an Android APK using Ninja, including building the Crashpad handler and loader_app, and then deploying and launching the APK on an Android device.

• The document details how to build and run nplb (native platform library) tests, including generating test results in XML format, along with debugging tips and how to remove the Cobalt Android environment.

These instructions explain how to build and run Cobalt for the AOSP platform (aosp-arm, aosp-arm64, aosp-x86).

Before following these instructions, make sure you have set up your workstation and source checkout as described in Set up your environment - Linux.

Prerequisites

1. Follow all steps in Set up your environment - Linux to install basic system dependencies, depot_tools, clone the Cobalt repository, and run build/install-build-deps.sh.

2. Ensure your root .gclient file includes android in target_os:

   target_os = [ 'linux', 'android' ]
   

   Then synchronize dependencies from your top-level repository:

   cd ~/cobalt/src
   gclient sync
   

3. Set up an Android debug keystore required for signing development APKs:

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

Build and Run Cobalt for AOSP

1. Configure the build directory for the target AOSP platform (aosp-arm, aosp-arm64, aosp-x86) using cobalt/build/gn.py.

   Use the -c flag to specify a build_type (debug, devel, qa, or gold).

   cobalt/build/gn.py -p aosp-arm -c devel --no-rbe
   

2. Compile the cobalt_loader target using autoninja:

   autoninja -C out/aosp-arm_devel cobalt_loader
   

   This generates the application loader APK at out/aosp-arm_devel/apks/cobalt.apk.

3. Deploy and launch on an AOSP device or emulator:

   Ensure your device is connected via ADB (adb devices or adb connect <device_ip>:5555).

   Install the compiled APK:

   adb install -r out/aosp-arm_devel/apks/cobalt.apk
   

   Launch the application using adb (Package: dev.cobalt.coat, Activity: dev.cobalt.app.MainActivity):

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

   Pass runtime flags using --esa commandLineArgs:

   adb shell am start --esa commandLineArgs 'url=https://www.youtube.com/tv' dev.cobalt.coat/dev.cobalt.app.MainActivity
   

   To force-stop any running instance before relaunching:

   adb shell am force-stop dev.cobalt.coat
   

Running Tests

The No Platform Left Behind (NPLB) test suite verifies Starboard implementation on AOSP targets.

1. Compile the NPLB test suite:

   cobalt/build/gn.py -p aosp-arm -c devel --no-rbe
   autoninja -C out/aosp-arm_devel nplb_loader
   

   This generates the test APK at out/aosp-arm_devel/apks/nplb.apk.

2. Install the NPLB test APK on the target device:

   adb install -r out/aosp-arm_devel/apks/nplb.apk
   

3. Launch NPLB on device passing the target compressed library argument via --esa commandLineArgs:

   adb shell "am start --esa commandLineArgs '--evergreen_library=app/cobalt/lib/libnplb.lz4,--evergreen_content=app/cobalt/content' dev.cobalt.coat/dev.cobalt.app.MainActivity"
   

4. Pass standard Google Test filtering arguments:

   # Run NPLB with a specific test filter (e.g. Memory tests)
   adb shell "am start --esa commandLineArgs '--evergreen_library=app/cobalt/lib/libnplb.lz4,--evergreen_content=app/cobalt/content,--gtest_filter=*Memory*' dev.cobalt.coat/dev.cobalt.app.MainActivity"
   

Debugging

To monitor log output, watch logcat with a filter for Starboard and Cobalt messages:

adb logcat -s "starboard:*" "Cobalt:*"

Clean up or reset the environment

To clean build artifacts:

gn clean out/aosp-arm_devel