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).
Download ‘depot_tools’, which is used to build the Cobalt code. An easy option is to put them in ~/depot_tools
. Clone the tools, by running the following command:
cd ~/ git clone https://cobalt.googlesource.com/depot_tools
Add your ‘depot_tools’ directory to the end of your PATH variable. We recommend adding something like this to your .bashrc
or .profile
file:
PATH=${PATH}:/path/to/depot_tools
Additional build dependencies may need to be installed:
sudo apt-get install python python-pip
If python-pip
is not available via your package mangaer, you can install pip
following recommended instructions from the official Python guide.
There are also some Python module requirements:
python -m pip install requests
Install ccache to support build acceleration. ccache is automatically used when available, otherwise defaults to unaccelerated building:
$ sudo apt-get install ccache
We recommend adjusting the cache size as needed to increase cache hits:
$ ccache --max-size=20G
Download and install Android Studio.
Run cobalt/build/gyp_cobalt android-x86
to configure the Cobalt build, which also installs the SDK and NDK. (This step will have to be repeated with ‘android-arm’ or ‘android-arm64’ to target those architectures.) The SDK and NDK will be downloaded and installed into a starboard-toolchains
directory as needed. If prompted, read and accept the license agreement to proceed forward.
Note: If you have trouble building with an error referencing the debug.keystore
you may need to set one up on your system:
keytool -genkey -v -keystore ~/.android/debug.keystore -storepass android -alias androiddebugkey -keypass android -keyalg RSA -keysize 2048 -validity 10000
Configure your device to be in developer mode:
Settings
, in the Device
row, select About
.Build
several times until a toast appears with the message, “You are now a developer.”For manually installing Android Studio and the SDK.
Note: Instructions moving forward are assuming a Linux environment.
$HOME/starboard-toolchains/AndroidSdk
$HOME/cobalt-toolchains/AndroidSdk
if you previously had an older environment configured on your machine - this is okay. * Select both Android SDK
and Android SDK Platform
(whatever current version is presented should be fine)SDK Platforms
tab select:starboard/android/apk
(just select the directory). This is “coat” (Cobalt On Android TV).build.gradle
in your git repo.Complete the Preliminary Setup above
Generate the cobalt.apk by building the “cobalt_deploy” target
ninja -C out/android-x86_gold cobalt_deploy
Output can be found in the corresponding out/android-x86_gold
directory.
Note: If you have trouble building with an error referencing the debug.keystore
you may need to set one up on your system:
keytool -genkey -v -keystore ~/.android/debug.keystore -storepass android -alias androiddebugkey -keypass android -keyalg RSA -keysize 2048 -validity 10000
Install the resulting APK into your test device with adb:
adb install out/android-x86_gold/cobalt.apk
Start the application with:
adb shell am start dev.cobalt.coat/dev.cobalt.app.MainActivity
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.:
adb shell am start --esa args --flag_arg,--value_arg=something dev.cobalt.coat
To monitor log output, watch logcat in another shell with a filter for starboard messages:
adb logcat -s starboard:*
To kill any existing running application process (even if it's no longer the active app) use:
adb shell am force-stop dev.cobalt.coat
Manually run cobalt/build/gyp_cobalt android-x86
in a shell. (You should do this after each time you sync your repo)
From the initial setup above, you should have opened the Android Studio project checked in at starboard/android/apk
.
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.
If you didn't install your Cobalt depot_tools in the standard location ($HOME/depot_tools
), then make starboard/android/apk/app/.cobaltrc
and set the DEPOT_TOOLS
envvar to the path to where you installed them (or make a symlink in the standard location to where you have them).
To run the app and attach the debugger: Run -> Debug ‘app’ (or in the toolbar)
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.
Note: If you have trouble building with an error referencing the debug.keystore
you may need to set one up on your system:
keytool -genkey -v -keystore ~/.android/debug.keystore -storepass android -alias androiddebugkey -keypass android -keyalg RSA -keysize 2048 -validity 10000
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>
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.
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.
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.)
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 “deploy” target (e.g. nplb_deploy). 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 ‘src’ directory:
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.
Unset ANDROID_HOME and or ANDROID_NDK_HOME in your shell and in .bashrc
Delete the SDK:
rm -rf ~/starboard-toolchains/AndroidSdk
Delete NDK toolchains:
rm -rf ~/starboard-toolchains/android*
Delete cached Android files:
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.