diff --git a/cobalt/site/docs/development/setup-android.md b/cobalt/site/docs/development/setup-android.md index 147d51813b66..518404b85b46 100644 --- a/cobalt/site/docs/development/setup-android.md +++ b/cobalt/site/docs/development/setup-android.md @@ -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 -1. Download and install [Android Studio](https://developer.android.com/studio/). +1. Download source code and setup build environment -1. To enable parallel gradle builds, add the following to your `~/.bashrc`: + Please checkout to the latest LTS version. Ex: 24.lts.40 - ``` - export COBALT_GRADLE_BUILD_COUNT=4 + ```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 ``` - Where 4 is the number of parallel threads. You can adjust the number of - parallel threads according to how your workstation performs. +1. Enter the top-level of the Cobalt directory -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. + ```sh + cd $COBALT_SRC + ``` - If prompted, read and accept the license agreement. +1. Download the Starboard toolchain and Android SDK -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.) + ```sh + ./starboard/tools/download_clang.sh + ./starboard/android/shared/download_sdk.sh + ``` - **Note:** If you have trouble building with an error referencing the - `debug.keystore` you may need to set one up on your system: +1. 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 + + ```sh 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 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 - - ) 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 - - 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. Enable python3 virtual environment + ```sh + python3 -m venv ~/.virtualenvs/cobalt_dev + source ~/.virtualenvs/cobalt_dev/bin/activate ``` - ninja -C out/android-x86_gold cobalt_install - ``` - Output can be found in the corresponding `out/android-x86_gold` directory. +### Download and configure the official Google-built Cobalt binaries from GitHub + +1. Create output directory for evergreen + + - Create the directory with arguments that meet the target device specification + - Platform type, ex: arm-hardfp, arm-softfp, arm-64, etc + - CPU type, ex: arm + - 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) + + - Choose the correct evergreen version based on the target device specification + + Please note that the selected prebuilt binary must meet the settings used to create evergreen directory in previous step. + - Cobalt version you checked out, ex: 24.lts.40 + - Build type, ex: gold, qa + - Starboard API version, 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 + - For Cobalt 25 with starboard API version 16, you need to use compressed version + - [`25.lts.1 release`](https://github.com/youtube/cobalt/releases/tag/25.lts.1) + - `Gold version`: cobalt_evergreen_5.1.2_arm-softfp_sbversion-16_release_compressed_20240629001855.crx + - `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 - **Note:** If you have trouble building with an error referencing the - `debug.keystore` you may need to set one up on your system: + ```sh + export LOCAL_CRX_DIR=/tmp/cobalt_dl + mkdir -p $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 ``` - keytool -genkey -v -keystore ~/.android/debug.keystore -storepass android -alias androiddebugkey -keypass android -keyalg RSA -keysize 2048 -validity 10000 + +1. Copy the files to the appropriate directories for building + + ```sh + cd $COBALT_SRC + mkdir -p out/evergreen-arm-softfp_qa/install/lib + cp -f $LOCAL_CRX_DIR/cobalt_prebuilt/lib/* out/evergreen-arm-softfp_qa/ + cp -f $LOCAL_CRX_DIR/cobalt_prebuilt/lib/* out/evergreen-arm-softfp_qa/install/lib + 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/ ``` -1. Install the resulting APK into your test device with adb: +### Compile Android APK using Ninja + +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" ``` - adb install out/android-x86_gold/cobalt.apk + + Note that we removed the `sb_evergreen_compatible_enable_lite` build param. + 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 + + ```sh + ninja -C out/android-arm_qa native_target/crashpad_handler + ``` + +1. Build loader_app APK + + ```sh + ninja -C out/android-arm_qa loader_app_install ``` -1. Start the application with: +1. Check the output apk file. The output file is available at + ```sh + out/android-arm_qa/loader_app.apk ``` + +## Setup your device and deploy the 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 +``` + +### Launch the APK + +1. Start the application with + + ```sh adb shell am start dev.cobalt.coat/dev.cobalt.app.MainActivity ``` @@ -151,83 +192,132 @@ 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: +1. 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" ``` + + - Via AndroidManifest.xml + ```sh + adb shell "am start 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: + 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 - - 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 + +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. + +### Build nplb library - **Note:** If you have trouble building with an error referencing the - `debug.keystore` you may need to set one up on your system: +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" ``` - keytool -genkey -v -keystore ~/.android/debug.keystore -storepass android -alias androiddebugkey -keypass android -keyalg RSA -keysize 2048 -validity 10000 + +1. Build nplb library + + ```sh + ninja -C out/evergreen-arm-softfp_devel nplb_install ``` -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: +1. Generate apk output folder - Run -> Edit Configurations… -> "app" -> General -> Launch Options -> Launch Flags + ```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" + ``` - e.g. To run with a different URL: `--esa args --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.) +### Build and run nplb test apk +1. Build nplb apk -## Running Tests + ```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 -``` -starboard/tools/testing/test_runner.py -p android-arm64 -c devel -b -r -t nplb -``` + ```sh + out/android-arm_devel/nplb_evergreen_loader.apk + ``` + +1. To run the nplb test, execute following command + + ```sh + # install the apk + adb install out/android-arm_devel/nplb_evergreen_loader.apk + + # launch the apk + 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 + + 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. + + ```sh + # create a file in a folder with read/write permission + adb shell "mkdir -p /data/local/tmp/" + adb shell "touch /data/local/tmp/nplb_testResult.xml" + + # Make the file writable + adb shell "chmod a+w /data/local/tmp/nplb_testResult.xml" + + # test and output to xml file + adb shell "am start --esa args '--evergreen_library=app/cobalt/lib/libnplb.so,--evergreen_content=app/cobalt/content,--gtest_output=xml:/data/local/tmp/nplb_testResult.xml' dev.cobalt.coat" + ``` -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. +### Build and run nplb evergreen compat test apk -## Debugging (Terminal) +1. Build nplb_evergreen_compat_tests apk + + **NOTE:** Please finish nplb build in previous step before building nplb compat test + + ```sh + ninja -C out/android-arm_devel nplb_evergreen_compat_tests_install + ``` + +1. 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 + + ```sh + # install the apk + adb install out/android-arm_devel/nplb_evergreen_compat_tests.apk + + # launch the apk + adb shell am start dev.cobalt.coat + ``` + +## Debugging Use `adb logcat` while Cobalt is running, or use `adb bugreport` shortly after exiting to view Android logs. You will need to filter or search for @@ -236,27 +326,50 @@ Cobalt-related output. As with the Linux build, use the `debug`, `devel`, or `qa` configs to trace Cobalt's callstacks. +### Build Cobalt library locally + +**Partners should always use the [Google prebuilt binaries from GitHub](https://github.com/youtube/cobalt/releases) +for certification or software release.** However, for testing or debugging, +they can still build the library locally. Ex: + + ```sh + # Create directory for evergreen-arm-softfp with build_type=qa and sb_api_version=15 + 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" + + # Build Cobalt library + ninja -C out/evergreen-arm-softfp_qa cobalt_install + ``` + + Once the Cobalt library is built, go back to [Compile Android APK using Ninja](#compile-android-apk-using-ninja) to build the APK. + ## Removing the Cobalt Android Environment 1. Unset ANDROID_HOME and or ANDROID_NDK_HOME in your shell and in .bashrc -1. Delete the SDK: - ``` +1. Delete the SDK + + ```sh rm -rf ~/starboard-toolchains/AndroidSdk ``` -1. Delete NDK toolchains: +1. Delete NDK toolchains - ``` + ```sh rm -rf ~/starboard-toolchains/android* ``` -1. Delete cached Android files: +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 + ``` diff --git a/cobalt/site/docs/development/setup-linux.md b/cobalt/site/docs/development/setup-linux.md index 889c4d079677..0d613125ad41 100644 --- a/cobalt/site/docs/development/setup-linux.md +++ b/cobalt/site/docs/development/setup-linux.md @@ -17,35 +17,35 @@ Required libraries can differ depending on your Linux distribution and version. 1. Run the following command to install packages needed to build and run Cobalt on Linux: - ``` - $ sudo apt update && sudo apt install -qqy --no-install-recommends \ - bison clang libasound2-dev libgles2-mesa-dev libglib2.0-dev \ - libxcomposite-dev libxi-dev libxrender-dev nasm ninja-build \ - python3.8-venv + ```sh + sudo apt update && sudo apt install -qqy --no-install-recommends \ + bison clang libasound2-dev libgles2-mesa-dev libglib2.0-dev \ + libxcomposite-dev libxi-dev libxrender-dev nasm ninja-build \ + python3-venv ``` 1. Install ccache to support build acceleration. Build acceleration is \ enabled by default and must be disabled if ccache is not installed. - ``` - $ sudo apt install -qqy --no-install-recommends ccache + ```sh + sudo apt install -qqy --no-install-recommends ccache ``` We recommend adjusting the cache size as needed to increase cache hits: - ``` - $ ccache --max-size=20G + ```sh + ccache --max-size=20G ``` 1. Install Node.js via `nvm`: - ``` - $ export NVM_DIR=~/.nvm - $ export NODE_VERSION=12.17.0 + ```sh + export NVM_DIR=~/.nvm + export NODE_VERSION=12.17.0 - $ curl --silent -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash + curl --silent -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash - $ . $NVM_DIR/nvm.sh \ + . $NVM_DIR/nvm.sh \ && nvm install --lts \ && nvm alias default lts/* \ && nvm use default @@ -58,8 +58,8 @@ Required libraries can differ depending on your Linux distribution and version. 1. Clone the Cobalt code repository. The following `git` command creates a `cobalt` directory that contains the repository: - ``` - $ git clone https://github.com/youtube/cobalt.git + ```sh + git clone https://github.com/youtube/cobalt.git ``` 1. Set `PYTHONPATH` environment variable to include the full path to the @@ -67,7 +67,7 @@ Required libraries can differ depending on your Linux distribution and version. the end of your ~/.bash_profile (replacing `fullpathto` with the actual path where you cloned the repo): - ``` + ```sh export PYTHONPATH="/fullpathto/cobalt:${PYTHONPATH}" ``` @@ -78,8 +78,10 @@ Required libraries can differ depending on your Linux distribution and version. 1. Enter your new `cobalt` directory: - ``` - $ cd cobalt + ```sh + cd cobalt + export COBALT_SRC=${PWD} + export PYTHONPATH=${PWD}:${PYTHONPATH} ```