Skip to content

Commit

Permalink
Update build instruction which enable evergreen on AOSP
Browse files Browse the repository at this point in the history 
b/318730771
  • Loading branch information
@jonastsai
jonastsai committed Jun 27, 2024
1 parent de09562 commit 2adec62
Showing 1 changed file with 149 additions and 157 deletions.
306 changes: 149 additions & 157 deletions cobalt/site/docs/development/setup-android.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,9 @@ Book: /youtube/cobalt/_book.yaml

# 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).
These instructions explain how to build Cobalt with evergreen enabled for your workstation and run the api on Android device.

## Preliminary Setup
## Build Instruction

<aside class="note">
<b>Note:</b> Before proceeding further, refer to the documentation for
Expand All @@ -15,134 +14,139 @@ sections <b>Set up your workstation</b> and <b>Set up developer tools</b>, then
return and complete the following steps.
</aside>

1. Download and install [Android Studio](https://developer.android.com/studio/).
`NOTE`: The below instructions assume a qa build intended for production. For non-qa builds, please replace qa with (gold, debug, devel) during GN generation and ninja building.

1. To enable parallel gradle builds, add the following to your `~/.bashrc`:
1. Download source code and setup build environment

Please checkout to the latest LTS version. Ex: 24.lts.40
```sh
git clone https://github.com/youtube/cobalt.git
cd cobalt
export COBALT_SRC=${PWD}
export PYTHONPATH=${PWD}
export COBALT_USE_INTERNAL_BUILD=0
git checkout tags/24.lts.40
```
export COBALT_GRADLE_BUILD_COUNT=4

1. Enter the top-level of the Cobalt directory:
```sh
cd $COBALT_SRC
```

Where 4 is the number of parallel threads. You can adjust the number of
parallel threads according to how your workstation performs.
1. Download the Starboard toolchain and Android SDK:
```sh
./starboard/tools/download_clang.sh
./starboard/android/shared/download_sdk.sh
```
If you encountered `Failed to find package patcher;v4` error, please edit starboard/android/shared/download_sdk.sh
and remove `"patcher;v4" \ ` near line 53.

1. Run `starboard/android/shared/download_sdk.sh` to download the SDK and NDK.
The SDK and NDK will be downloaded and installed into
`~/starboard-toolchains`. If you wish to customize the download location
you must set the relevant environment variables accordingly.
1. Install additional Linux packages:
```sh
sudo apt install binutils-arm-linux-gnueabi libgles2-mesa-dev mesa-common-dev
```

If prompted, read and accept the license agreement.
1. Make sure Android debug keystore is setup:
```sh
keytool -genkey -v -keystore ~/.android/debug.keystore -storepass android -alias androiddebugkey -keypass android -keyalg RSA -keysize 2048 -validity 10000
```

1. Run `cobalt/build/gn.py -p android-x86` to configure the Cobalt build.
(This step will have to be repeated with 'android-arm' or 'android-arm64'
to target those architectures.)
1. Enable python3 virtual environment
```sh
python3 -m venv ~/.virtualenvs/cobalt_dev
source ~/.virtualenvs/cobalt_dev/bin/activate
```

**Note:** If you have trouble building with an error referencing the
`debug.keystore` you may need to set one up on your system:
### Download and configure the official Google-built Cobalt binaries from GitHub

```
keytool -genkey -v -keystore ~/.android/debug.keystore -storepass android -alias androiddebugkey -keypass android -keyalg RSA -keysize 2048 -validity 10000
1. Create output directory for evergreen
```sh
gn gen out/evergreen-arm-softfp_qa --args="target_platform=\"evergreen-arm-softfp\" use_asan=false target_cpu=\"arm\" build_type=\"qa\" sb_api_version=15"
```

## Setup your device
1. Select Google-prebuilt Cobalt binaries from [GitHub](https://github.com/youtube/cobalt/releases)

Configure your device to be in developer mode:
- Choose the correct evergreen version based on
- the Cobalt version you checked out, ex: 24.lts.40
- the build type, ex: gold, qa
- the starboard API versioin, ex: 15
- Here is an example of 24.lts.40 with starboard API version 15
- [`24.lts.40 release`](https://github.com/youtube/cobalt/releases/tag/24.lts.40)
- `Gold version`: cobalt_evergreen_4.40.2_arm-softfp_sbversion-15_release_20240426165046.crx
- `QA version`: cobalt_evergreen_4.40.2_arm-softfp_sbversion-15_qa_20240426165046.crx
- Right click the file and copy file URL

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 gn gen for an
android target, so you'll see a warning in the setup wizard that an SDK
was detected, which 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_install" target
1. Download and unzip the file
```sh
export LOCAL_CRX_DIR=/tmp/cobalt_dl
mkdir $LOCAL_CRX_DIR
# paste prebuilt library URL and Download it to /tmp
# Please update URL according to your need
COBALT_CRX_URL=https://github.com/youtube/cobalt/releases/download/24.lts.40/cobalt_evergreen_4.40.2_arm-softfp_sbversion-15_qa_20240426165046.crx
wget $COBALT_CRX_URL -O $LOCAL_CRX_DIR/cobalt_prebuilt.crx
# Unzip the downloaded CRX file
unzip $LOCAL_CRX_DIR/cobalt_prebuilt.crx -d $LOCAL_CRX_DIR/cobalt_prebuilt
```
ninja -C out/android-x86_gold cobalt_install

1. Copy the files to the appropriate directories for building:
```sh
cd $COBALT_SRC
cp -f $LOCAL_CRX_DIR/cobalt_prebuilt/lib/libcobalt.so out/evergreen-arm-softfp_qa/
cp -f $LOCAL_CRX_DIR/cobalt_prebuilt/manifest.json out/evergreen-arm-softfp_qa/
cp -rf $LOCAL_CRX_DIR/cobalt_prebuilt/content out/evergreen-arm-softfp_qa/
```

Output can be found in the corresponding `out/android-x86_gold` directory.
### Compile Android APK using Ninja

**Note:** If you have trouble building with an error referencing the
`debug.keystore` you may need to set one up on your system:
1. Generate output folder
```sh
gn gen out/android-arm_qa --args="target_platform=\"android-arm\" target_os=\"android\" target_cpu=\"arm\" build_type=\"qa\" sb_api_version=15 sb_is_evergreen_compatible=true"
```

2. Build Crashpad handler first
```sh
ninja -C out/android-arm_qa native_target/crashpad_handler
```
keytool -genkey -v -keystore ~/.android/debug.keystore -storepass android -alias androiddebugkey -keypass android -keyalg RSA -keysize 2048 -validity 10000

3. Build loader_app APK
```sh
ninja -C out/android-arm_qa loader_app_install
```
The generated APK file is available at out/android-arm_qa/loader_app.apk

1. Install the resulting APK into your test device with adb:
## Setup your device and deploy the apk

```
adb install out/android-x86_gold/cobalt.apk
```
### Configure your device to be in developer mode:

1. From `Settings`, in the `System` row, select `About`.
1. Scroll down to and click on `Android TV OS 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.

`Note:` This instruction is based on Chromecast (Google TV). If you do not find the same setting, please check similar setting under **System, About and Build**.

### Check the device is connected

1. Connect your workstation with the Android device via USB
1. Check device is connected
```sh
adb devices
# It shows the device if it is connected
List of devices attached
35091HFGN5HVC2 device
```

### Install the Evergreen loader APK on the device:
```
adb install out/android-arm_qa/loader_app.apk
```

1. Start the application with:

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

Expand All @@ -151,81 +155,63 @@ Go ahead and click 'yes' to open the SDK manager to install the following:
make it through both the shell on your workstation and the shell on the
device), e.g.:

```
```sh
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:

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

1. To kill any existing running application process (even if it's no longer the
active app) use:
```
```sh
adb shell am force-stop dev.cobalt.coat
```
## Building/running/debugging (Android Studio IDE)
1. Manually run `cobalt/build/gn.py -p 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. 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.
## Running Tests
**Note:** If you have trouble building with an error referencing the
`debug.keystore` you may need to set one up on your system:
There is no prebuilt nplb library on github server and the partners can build it
from the source code. The build target just builds an .so file (e.g. libnplb.so). To
run that on a device, it needs to be packaged into another loader APK. Here is the
instruction to build `devel` version. You can change to `debug` according to your need.
### Build nplb library
1. Generate evergreen folder
```sh
gn gen out/evergreen-arm-softfp_devel --args=target_platform=\"evergreen-arm-softfp\" target_cpu=\"arm\" use_asan=false build_type=\"devel\"
```
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.)
1. Build nplb library
```sh
ninja -C out/evergreen-arm-softfp_devel nplb_install
```
1. Generate apk output folder
```sh
gn gen out/android-arm_devel --args=target_platform=\"android-arm\" target_cpu=\"arm\" target_os=\"android\" sb_is_evergreen_compatible=true build_type=\"devel\"
```
## Running Tests
1. Build nplb apk
```sh
ninja -C out/android-arm_devel nplb_evergreen_loader_install
```
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 "install" target (e.g. nplb_install). 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-level directory:
1. Check the output apk file. The output file is available at:
```sh
out/android-arm_devel/nplb_evergreen_loader.apk
```
### Run nplb test
To run the nplb test, execute following command:
```sh
adb shell "am start --esa args '--evergreen_library=app/cobalt/lib/libnplb.so,--evergreen_content=app/cobalt/content' dev.cobalt.coat"
```
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.
## Debugging (Terminal)
Expand All @@ -241,22 +227,28 @@ Cobalt's callstacks.
1. Unset ANDROID_HOME and or ANDROID_NDK_HOME in your shell and in .bashrc
1. Delete the SDK:

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

1. Delete NDK toolchains:

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

1. Delete cached Android files:

```
```sh
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.

1. Uninstall APK from device

```sh
adb uninstall dev.cobalt.coat
```

0 comments on commit 2adec62

Please sign in to comment.