Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Evergreen docs polish #4136

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Evergreen docs polish #4136

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 71 additions & 69 deletions cobalt/site/docs/development/setup-android.md
View file
Open in desktop
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we update the number of markdown numbered list manually?

Leave it as 1. and allow the render to automatic numbering should be good enough.

We can easily insert/remove or update the order of the list without affecting others.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll revert that part.

I updated it because g3doc recommends using "correct" numbering. Markdown supports both ways and I didn't see any preference in the developer site docs. The developer site markdown formatter don't seem to touch them unlike the regular g3doc markdown formatter.


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