android

Android Development Instructions

This document describes how to develop and debug for Android.

The main entrypoint to Android's Java code is client/src/cordova/plugin/android/java/org/outline/OutlinePlugin.java

Set up your environment

Install these pre-requisites:

• Java Development Kit (JDK) 17+. On macOS:

  brew install openjdk@17
  
  # Make it visible to `java_home`
  sudo ln -sfn "$(realpath "$(brew --prefix)")/opt/openjdk@17/libexec/openjdk.jdk" /Library/Java/JavaVirtualMachines/openjdk-17.jdk
  
  export JAVA_HOME=$(/usr/libexec/java_home -v 17.0)

• Gradle 8.14.2+. On macOS: brew install gradle.

Then we need to install and configure the Android components. You can follow the Cordova Android Platform Guide, which uses Android Studio to configure the environment. You need an Android Studio compatible with the Android Gradle Plugin 8.10.1 (see build.gradle) we use (compatibility table).

Alternatively, you can do it on the command-line:

1. Set environmental variables:

   export ANDROID_HOME=$HOME/Library/Android/sdk
   export ANDROID_NDK=$ANDROID_HOME/ndk

2. Install the Android command-line tools and make them available on the command line:

   curl -o /tmp/commandlinetools.zip https://dl.google.com/android/repository/commandlinetools-mac-13114758_latest.zip
   unzip /tmp/commandlinetools.zip -d /tmp
   mkdir -p "$ANDROID_HOME/cmdline-tools/latest"
   mv /tmp/cmdline-tools/* "$ANDROID_HOME/cmdline-tools/latest/"
   export PATH="$PATH:$ANDROID_HOME/cmdline-tools/latest/bin/"

3. Install platform and build tools:

   sdkmanager "platforms;android-36" "build-tools;36.0.0" "ndk;28.2.13676358" 

   The NDK version must match the ndkVersion pin in build-extras.gradle, whose comment explains why we pin it (AGP uses it to strip the packaged native libraries).

4. Install optional components that help development (source code, emulator and image):

   sdkmanager "sources;android-36" "system-images;android-36;default;arm64-v8a"

Note: you will need the system-images;android-36;default;x86_64 image on an Intel computer.

For development of the OutlineAndroidLib, we recommend installing Android Studio. That also make it easier to create virtual devices and run the emulator.

You can check your environment with:

npm run action client/src/cordova/setup android
cd client
npx cordova requirements android

Important Versions

Component	version	constrained by	set in
Android API Level	36+	Play Store	config.xml, build.gradle
cordova-android	15	Android API Level	package.json
JDK	17	cordova-android	install instruction
Gradle	8.14.2+	cordova-android	gradle-wrapper.properties
Android Gradle Plugin (AGP)	8.10.1	cordova-android	build.gradle
Android Build Tools	36.0.0+	cordova-android	install instructions
Android NDK	28.2.13676358	native-lib stripping	build-extras.gradle, install instructions
Android Studio	2025.1.1 (Narwhal)	AGP

Build the app

To build the app for Android, run:

  npm run action client/src/cordova/build android

The built apk will be at: client/platforms/android/app/build/outputs/apk/debug/app-debug.apk.

We also support passing a --verbose option on cordova android:

  npm run action client/src/cordova/build android -- --verbose

Make sure to rebuild after modifying platform dependent files!

💡 NOTE: If this command ever gives you unexpected Cordova errors, try runnning npm run reset first.

Run the app

1. Start the simulator or connect an Android device and enable USB debugging.

2. From the project root, run:

   adb install -r -d client/platforms/android/app/build/outputs/apk/debug/app-debug.apk

Alternatively, run with:

cd client
npx cordova run android -- --gradleArg=--include-build=../../src/cordova/android/OutlineAndroidLib

Develop code

Open src/cordova/android/OutlineAndroidLib on Android Studio. That will allow you to leverage the IDE features (auto-complete, warnings, etc) and run unit tests easily.

This project represents a library that implements most of the Outline native functionality and does not depend on Cordova. That library is imported by the "app" module that is generated by Cordova. The only native Android code outside of this library is OutlinePlugin.java, which integrates with CordovaLib.

To make the entire application load properly on Android Studio, you need to edit the generated /client/platforms/android/settings.gradle and add:

includeBuild "../../src/cordova/android/OutlineAndroidLib"

To debug the web app

Run Outline on your phone with USB debugging enabled, then on Chrome:

• Go to chrome://inspect
• Find Outline
• Click inspect
• Open the Console
• Note that all TypeScript code is browserified in a single main.cordova.js

To debug Java code

You can debug the Java code using logcat on Android Studio:

1. Start the app
2. Select the "Logcat" tab at the bottom
3. Select org.outline.android.client in the middle menu (it should not say "no debuggable processes")

It's also possible to use the logcat command.