Running Wrench on Android devices.
==================================

Setting up the environment:
---------------------------

Follow the steps at https://github.com/rust-windowing/android-rs-glue#setting-up-your-environment, with exceptions:
    - No need to download the Android NDK and SDK, we will use the ones downloaded by Gecko in ~/.mozbuild/

    - Install both the i686-linux-android and armv7-linux-androideabi rust
      targets, as the APK will include native libraries with both architectures.

    - Don't install currently published version of cargo-apk, as it is missing the following
      required patch: https://github.com/rust-windowing/android-ndk-rs/pull/236

      Instead, install the git master version like so:
        cargo install --git https://github.com/rust-windowing/android-ndk-rs cargo-apk

    - Consider adding ~/.mozbuild/android-sdk-linux/platform-tools to your path, for the adb commands below.

Compiling and running:
----------------------

    Compile wrench:
        cd wrench
        export ANDROID_SDK_ROOT=$HOME/.mozbuild/android-sdk-linux # exact path may vary
        export ANDROID_NDK_ROOT=$HOME/.mozbuild/android-ndk-r21d  # exact path may vary
        cargo apk build --lib

    Install the APK:
        adb install -r ../target/debug/apk/wrench.apk

    Set command line arguments and env vars for wrench:
        adb shell
        mkdir /data/data/org.mozilla.wrench/files/wrench
        echo "load reftests/aa/rounded-rects.yaml" >/data/data/org.mozilla.wrench/files/wrench/args
        echo "env: WRENCH_REFTEST_CONDITION_EMULATOR=1" >>/data/data/org.mozilla.wrench/files/wrench/args # If you're using the emulator
        echo "env: WRENCH_REFTEST_CONDITION_DEVICE=1" >>/data/data/org.mozilla.wrench/files/wrench/args # If you're using a device
        exit

    Push reftests (if you need these files for what you're doing):
        adb push reftests /data/data/org.mozilla.wrench/files/wrench/

    Run the application:
        adb shell am start -n org.mozilla.wrench/android.app.NativeActivity
            (or click the icon in the launcher)

    Inspect the output:
        stdout and stderr will be redirected to the logcat, however, long lines will be truncated
        meaning the reftest analyzer will not work correctly. We therefore additionally redirect the
        output to the file /data/data/org.mozilla.wrench/files/wrench/stdout.

Release mode:
-------------

    Building in release does work as well. Use the following steps to compile wrench:
        cd wrench
        export ANDROID_SDK_ROOT=$HOME/.mozbuild/android-sdk-linux # exact path may vary
        export ANDROID_NDK_ROOT=$HOME/.mozbuild/android-ndk-r21d  # exact path may vary
        cargo apk build --lib --release

    Now the APK at ../target/release/apk/wrench.apk
    should be signed and installable (you may need to uninstall the debug APK first if you
    have that installed).

Running reftests like a boss (on a local emulator):
---------------------------------------------------

    First, compile wrench as described above (debug mode).
    Then, from the root gecko source dir, run:
        ./mach python testing/mozharness/scripts/android_wrench.py --config testing/mozharness/configs/android/wrench.py
    This will automatically do the following:
        - Download the blessed android AVDs from taskcluster
        - Start the emulator (using your ~/.mozbuild/android-sdk-linux emulator binaries)
        - Install the debug APK (from gfx/wr/wrench/target/debug/apk/wrench.apk)
        - Copy the reftests to the sdcard
        - Write an args file to the sdcard
        - Run wrench
        - Wait for wrench to finish running
        - Scrape the logcat for reftest output
    Other logs (e.g. full logcat) can be found in your ~/.wrench/logs folder. Note that
    this will also leave the android emulator running, so repeating the command will be
    even faster the next time around as it won't need to redownload the AVDs or restart
    the emulator. It will reinstall the APK and re-push the reftests folder though.

    If you want to use a release APK (runs much faster), build it as per the "Release mode"
    instructions above and set the WRENCH_APK env var to point to the APK:
    to point to it:
        export WRENCH_APK=gfx/wr/target/release/apk/wrench.apk
        ./mach python testing/mozharness/scripts/android_wrench.py --config testing/mozharness/configs/android/wrench.py

Running reftests like a boss (on a local device):
-------------------------------------------------

    Same steps as running on a local emulator, except you need to do this:
        export DEVICE_SERIAL=<your device's serial>
    before running the `./mach python` command. You can get the serial of
    your device by running `adb devices` with the device plugged in. When running
    on a device, the android_emulator_wrench.py script will skip the steps to
    download the AVDs and start the emulator.