Skip to content

Commit

Permalink
Evergreen docs polish
Browse files Browse the repository at this point in the history 
Ran it through the linter and fixed errors and warnings.

b/318730771
  • Loading branch information
@oxve
oxve committed Sep 19, 2024
1 parent e3a485c commit 2758545
Show file tree
Hide file tree
Showing 3 changed files with 238 additions and 218 deletions.
140 changes: 71 additions & 69 deletions cobalt/site/docs/development/setup-android.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,32 +27,32 @@ return and complete the following steps.
git checkout tags/24.lts.40
```

1. Enter the top-level of the Cobalt directory
2. Enter the top-level of the Cobalt directory

```sh
cd $COBALT_SRC
```

1. Download the Starboard toolchain and Android SDK
3. Download the Starboard toolchain and Android SDK

```sh
./starboard/tools/download_clang.sh
./starboard/android/shared/download_sdk.sh
```

1. Install additional Linux packages
4. Install additional Linux packages

```sh
sudo apt install binutils-arm-linux-gnueabi libgles2-mesa-dev mesa-common-dev
```

1. Make sure Android debug keystore is setup
5. 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. Enable python3 virtual environment
6. Enable python3 virtual environment

```sh
python3 -m venv ~/.virtualenvs/cobalt_dev
Expand All @@ -69,11 +69,12 @@ return and complete the following steps.
- Build type, ex: gold, qa
- Starboard API version, ex: 15
- An example to create directory for evergreen-arm-softfp with build_type=qa and sb_api_version=15

```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"
```

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

- Choose the correct evergreen version based on the target device specification

Expand All @@ -91,7 +92,7 @@ return and complete the following steps.
- `QA version`: cobalt_evergreen_5.1.2_arm-softfp_sbversion-16_qa_compressed_20240629001855.crx
- Right click the file and copy file URL

1. Download and unzip the file
3. Download and unzip the file

```sh
export LOCAL_CRX_DIR=/tmp/cobalt_dl
Expand All @@ -107,7 +108,7 @@ return and complete the following steps.
unzip $LOCAL_CRX_DIR/cobalt_prebuilt.crx -d $LOCAL_CRX_DIR/cobalt_prebuilt
```

1. Copy the files to the appropriate directories for building
4. Copy the files to the appropriate directories for building

```sh
cd $COBALT_SRC
Expand All @@ -130,19 +131,19 @@ return and complete the following steps.
To enable Evergreen-lite, you may either pass in command line flag `--evergreen_lite` or
set the `cobalt.EVERGREEN_LITE` property to be `true` in the AndroidManifest.xml

1. Build Crashpad handler first
2. Build Crashpad handler first

```sh
ninja -C out/android-arm_qa native_target/crashpad_handler
```

1. Build loader_app APK
3. Build loader_app APK

```sh
ninja -C out/android-arm_qa loader_app_install
```

1. Check the output apk file. The output file is available at
4. Check the output apk file. The output file is available at

```sh
out/android-arm_qa/loader_app.apk
Expand All @@ -152,19 +153,19 @@ return and complete the following steps.

### 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
1. From `Settings`, in the `System` row, select `About`
2. Scroll down to and click on `Android TV OS build` several times until a
toast appears with the message, "You are now a developer"
3. 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
2. Check device is connected

```sh
adb devices
Expand All @@ -175,53 +176,53 @@ return and complete the following steps.

### Install the Evergreen loader APK on the device

```
```sh
adb install out/android-arm_qa/loader_app.apk
```

### Launch the APK

1. Start the application with
1. Start the application with

```sh
adb shell am start dev.cobalt.coat/dev.cobalt.app.MainActivity
```
```sh
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.:
2. 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.:

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

1. For Evergreen-lite, two ways to launch it depending on how you enable it
- Via command line flag
3. For Evergreen-lite, two ways to launch it depending on how you enable it
- Via command line flag

```sh
adb shell "am start --esa args '--evergreen_lite=true' dev.cobalt.coat"
```
```sh
adb shell "am start --esa args '--evergreen_lite=true' dev.cobalt.coat"
```

- Via AndroidManifest.xml
```sh
adb shell "am start dev.cobalt.coat"
```
- Via AndroidManifest.xml

1. To monitor log output, watch logcat in another shell with a filter for
starboard messages
```sh
adb shell "am start dev.cobalt.coat"
```

```sh
adb logcat -s starboard:*
```
4. To monitor log output, watch logcat in another shell with a filter for
starboard messages

1. To kill any existing running application process (even if it's no longer the
active app) use
```sh
adb logcat -s starboard:*
```

```sh
adb shell am force-stop dev.cobalt.coat
```
5. 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
```
## Running Tests
Expand All @@ -232,19 +233,20 @@ run that on a device, it needs to be packaged into another loader APK.
### Build nplb library
Similar to loader_app, create the directory with arguments that meet the target device specification. Here is an example:
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\" sb_api_version=15"
```
1. Build nplb library
2. Build nplb library
```sh
ninja -C out/evergreen-arm-softfp_devel nplb_install
```
1. Generate apk output folder
3. 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\" sb_api_version=15"
Expand All @@ -258,13 +260,13 @@ Similar to loader_app, create the directory with arguments that meet the target
ninja -C out/android-arm_devel nplb_evergreen_loader_install
```
1. Check the output apk file. The output file is available at
2. Check the output apk file. The output file is available at
```sh
out/android-arm_devel/nplb_evergreen_loader.apk
```
1. To run the nplb test, execute following command
3. To run the nplb test, execute following command
```sh
# install the apk
Expand All @@ -274,7 +276,7 @@ Similar to loader_app, create the directory with arguments that meet the target
adb shell "am start --esa args '--evergreen_library=app/cobalt/lib/libnplb.so,--evergreen_content=app/cobalt/content' dev.cobalt.coat"
```
1. Generate test result with XML format
4. Generate test result with XML format
Due to access permission constrains on AOSP, the xml file should be created
by `adb shell` first, before nplb apk writing test result in it.
Expand All @@ -301,13 +303,13 @@ Similar to loader_app, create the directory with arguments that meet the target
ninja -C out/android-arm_devel nplb_evergreen_compat_tests_install
```
1. Check the output apk file. The output file is available at
2. Check the output apk file. The output file is available at
```sh
out/android-arm_devel/nplb_evergreen_compat_tests.apk
```
1. To run the nplb compat test, execute following command
3. To run the nplb compat test, execute following command
```sh
# install the apk
Expand Down Expand Up @@ -344,31 +346,31 @@ they can still build the library locally. Ex:

## Removing the Cobalt Android Environment

1. Unset ANDROID_HOME and or ANDROID_NDK_HOME in your shell and in .bashrc
1. Unset ANDROID_HOME and or ANDROID_NDK_HOME in your shell and in .bashrc

1. Delete the SDK
2. Delete the SDK

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

1. Delete NDK toolchains
3. Delete NDK toolchains

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

1. Delete cached Android files
4. Delete cached Android files

```sh
rm -rf ~/.android
```
```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
5. Uninstall APK from device

```sh
adb uninstall dev.cobalt.coat
Expand Down
Loading

0 comments on commit 2758545

Please sign in to comment.