Building the Android Components

Doing a local build of the Android Components:

This document describes how to make local builds of the Android components in this repository. Most consumers of these components do not need to follow this process, but will instead use pre-built components [todo: link to this]

This document, and the build process itself, is a work-in-progress - please file issues (or just update the wiki!) if you notice errors or omissions.

Prepare your build environment

NOTE: This section is almost certainly incomplete - given it is typically only done once, things have probably been forgotten or over-simplified. Please file PRs if you notice errors or omissions here

This process should work OK on Mac and Linux. It might even work OK for some components on Windows, but that's currently a bit hit-and-miss.

Typically, this process only needs to be run once, although periodically you may need to repeat some steps (eg, rust updates should be done periodically)

At the end of this process you should have the following environment variables set up.

• NDK_HOME
• ANDROID_NDK_TOOLCHAIN_DIR
• ANDROID_NDK_API_VERSION

These variables are required every time you build, so you should add them to a rc file or similar so they persist between reboots etc.

1. Install NDK r15c from https://developer.android.com/ndk/downloads/older_releases (yes, this sucks, but newer versions don't understand the --deprecated-headers argument required to build OpenSSL against a v21 toolchain).

   • Extract it, put it somewhere ($HOME/.android-ndk-r15c is a reasonable choice, but it doesn't matter), and set NDK_HOME to this location.

2. Install rustup from https://rustup.rs:

   • If you already have it, run rustup update
   • Run rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android
   • Run rustup toolchain add beta (TODO: this may not still be necessary, but just to be safe...).

3. Ensure your clone of mozilla/application-services is up to date.

4. Setup your NDK toolchains.

   • Create a directory where we'll install the standalone toolchains.
     • mkdir -p ~/.ndk-standalone-toolchains
     • export ANDROID_NDK_TOOLCHAIN_DIR=$HOME/.ndk-standalone-toolchains
   • cd path/to/application-services/libs
   • ./setup_toolchains_local.sh $NDK_HOME
     • Say yes if/when prompted.
     • When this is done, it should have set $ANDROID_NDK_API_VERSION (to 21), but you should add this to an rcfile as above.

5. Build openssl and sqlcipher

   • cd path/to/application-services/libs (Same dir you were just in for step 4)
   • ./build-all.sh android (Go make some coffee or something, this will take some time as it has to compile sqlcipher and openssl for x86, arm, and arm64).
   • Note that if something goes wrong here
     • Check all environment variables mentions above are set and correct.
     • The following directories should exist, and point to standalone NDK toolchains $ANDROID_NDK_TOOLCHAIN_DIR/{x86,arm,arm64}-$ANDROID_NDK_API_VERSION.

Building

Having done the above, the build process is the easy part! Again, ensure all environment variables mentioned above are in place.

1. Ensure your clone of application-services is up-to-date.

2. Ensure rust is up-to-date by running rustup

3. The build are all performed by ./gradlew and the general syntax used is ./gradlew project:task

   You can see a list of projects by executing ./gradlew projects and a list of tasks by executing ./gradlew tasks.

   Most of the time you will want one of the assemble tasks - either assembleDebug or assembleRelease.

For example, to build a debug version of the places library, the command you want is ./gradlew places-library:assembleDebug

After building, you should find the built artifact under the target directory, with sub-directories for each Android architecture. For example, after executing:

% ./gradlew places-library:assembleDebug

you will find:

target/aarch64-linux-android/release/libplaces_ffi.so
target/i686-linux-android/release/libplaces_ffi.so
target/armv7-linux-androideabi/release/libplaces_ffi.so

(You will probably notice that even though as used assembleDebug, the directory names are release - this may change in the future)

You can then copy the files into your Android Studio project.