android.txt - mozsearch

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.