Setup

Table of Contents

• Requirements
• Setting Up Environment and Dependencies
  • Linux
    • Ubuntu 22.04 (command-line only)
    • Ubuntu 18.04
    • Other
  • macOS

Requirements

• Python 3
• Linux or macOS

Current and former contributors have used Ubuntu 18.04 and Ubuntu 20.04 along with Python 3.6.9 and 3.7.4.

Setting Up Environment and Dependencies

1. Click on the Fork icon in the top right hand corner once you're logged into Github.
2. Once it finishes loading, click on the green Code button. Copy git clone [email protected]:[your_username]/android-runner.git and then paste that into your terminal after navigating to the desired local development environment.
3. Type cd android-runner to enter the framework's main directory. Now, add a remote tracker to the parent repository with git remote add upstream https://github.com/S2-group/android-runner. This is useful in case any major changes occur to the parent directory that may affect your project. git remote -vv should now show origin and upstream.
4. Create a virtual environment: python3 -m venv /path/. This can be anywhere on your machine. Activate it with source /path/bin/activate.
5. Install dependencies:
   1. Select your platform below:

      Linux

      Ubuntu 22.04 (command-line only)

      • Install JDK 11 sudo apt install openjdk-11-jre.
      • Download thesdkmanager from the latest "command line tools only" package available here and unzip the package to your $HOME directory.
      • Create a directory called android-sdk in your $HOME directory and move the unzipped cmdline-tools directory there.
      • In the directory cmdline-tools create a sub-directory called latest.
      • Move all the original contents from cmdline-tools into the newly created latest directory.
      • cd into cmdline-tools/latest/bin and run the following commands to install adb and monkeyrunner:

          ./sdkmanager "platform-tools"
          ./sdkmanager "build-tools;30.0.0"

      • Add the following to your .bashrc or .zshrc file:

          export PATH=$HOME/android-sdk/cmdline-tools/latest/bin:$PATH
          export PATH=$HOME/android-sdk/platform-tools:$PATH
          export PATH=$HOME/android-sdk/tools/bin:$PATH

      • Reload your .bashrc or .zshrc settings by running source ~/.bashrc or source ~/.zshrc
      • To verify if everything works correctly run adb --version. This should return its version number and install location. To do the same for Monkey Runner run monkeyrunner --version. This should return a Unrecognized argument: --version. but no other errors.
      • Install lxml using sudo apt install python3-lxml (assuming python3 is being used).

      Ubuntu 18.04

      • Android Debug Bridge (sudo apt install android-tools-adb)
      • Android SDK Tools (sudo apt install monkeyrunner)
      • JDK 11 (sudo apt install openjdk-11-jre)
        • See this for switching between java versions
      • lxml (sudo apt install python-lxml)

      Other

      • Download Android Studio from here.

      • Extract the archive, cd into its directory and install Android Studio by running ./bin/studio.sh

      • During the setup wizard Android Studio will ask you where you want to install the Android SDK. By default it is in /home/user/Android/Sdk

      • The Android SDK, including ADB and Monkey Runner, is now installed on your system. To access the Android tools directly via your shell (preferable) add the following to your .bashrc/.zshrc:

        export ANDROID_HOME=$HOME/Android/Sdk
        export PATH=$PATH:$ANDROID_HOME/tools/bin
        export PATH=$PATH:$ANDROID_HOME/platform-tools
        

      • Reload your .bashrc or .zshrc settings by running source ~/.bashrc or source ~/.zshrc

      • Since MonkeyRunner requires JDK 8 (not JDK 9) we need to install JDK 8: sudo apt install openjdk-8-jre.

        • Once JDK 8 is installed we need to actually set it as default. See here how to do that.

      • To verify if everything works correctly run adb --version. This should return its version number and install location. To do the same for Monkey Runner run monkeyrunner --version. This should return a Unrecognized argument: --version. but no other errors.

      • Install lxml using sudo apt install python-lxml.

      macOS

      • Make sure you have Homebrew installed
      • brew install --cask homebrew/cask-versions/adoptopenjdk8 android-sdk android-platform-tools
      • brew install libxml2
      • Run java -version, if you are running a different version than 1.8/8:
      • brew install jenv
        • Run /usr/libexec/java_home -V to see the location of your Java environments
        • Copy the location of your AdoptOpenJDK8 environment
        • Run jenv add <AdoptOpenJDK8_path>
        • Run jenv global 1.8
        • Restart terminal and verify your Java version with java -version, it should output openjdk version "1.8.0_265"
      • Verify that monkeyrunner works with monkeyrunner --version, it should output unrecognized argument and no other errors
   2. Within Android Runner's main directory
      • pip install -r requirements.txt
   3. For creating or editing unit tests to ensure pull request passes TravisCI
      • pip install pytest mock

Note: It is important that Monkeyrunner shares the same adb the experiment is using. Otherwise, there will be an adb restart and output may be tainted by the notification. You can specify the path to adb and/or Monkeyrunner in the experiment configuration file.

Note 2: The Batterystats, Trepn and Monsoon plugins have additional dependencies. Refer to the plugin READMEs for more information.