Skip to content

Latest commit

 

History

History
157 lines (103 loc) · 6.98 KB

BUILD_ANDROID.md

File metadata and controls

157 lines (103 loc) · 6.98 KB
Raw

Build Android

Last Updated on December 15, 2020

Warning

Android building is currently broken, due to breaking changes in Qt and Gradle. Help with updating (or rewriting) the Gradle scripts would be great.

Please read the general build guide for information on building other platforms. Only Android specific instructions are found in this file. Note that these instructions apply to building for the Oculus Quest 1.

Dependencies

Building is currently supported on Windows, OSX and Linux, but developers intending to do work on the library dependencies are strongly urged to use 64 bit Linux as a build platform.

OS specific dependencies

Please install the dependencies for your OS using the Windows, OSX or Linux build instructions before attempting to build for Android.

Android Studio

Download the Android Studio installer and run it. Once installed, click File then Settings, expand Appearance & Behavior then expand System Settings and select Android SDK.

From the SDK Platforms tab, select API levels 26 and 28.

From the SDK Tools tab, select the following

  • Android SDK Build-Tools
  • GPU Debugging Tools
  • LLDB
  • Android SDK Platform-Tools
  • Android SDK Tools
  • NDK (even if you have the NDK installed separately)

Still in the SDK Tools tab, check off Show Package Details at the bottom. Select CMake 3.6.4. Do this even if you have a separate CMake installation. Also, make sure the NDK installed version is 18 (or higher).

Now go back to File then Project Structure then under Project set the Android Gradle Plugin Version to 3.2.1 and Gradle Version to 4.10.1.

If Android Studio pops open the "Plugin Update Recommeded" dialog, do not click update, just click X on the top right to close. Later versions of the Gradle plugin have known issues with cz.malohlava.

Environment

Create a keystore in Android Studio

Follow the directions here to create a keystore file. You can save it anywhere (preferably not in the overte folder).

Set up machine specific Gradle properties

Create a gradle.properties file in the .gradle folder ($HOME/.gradle on Unix, Users/<yourname>/.gradle on Windows). Edit the file to contain the following

HIFI_ANDROID_PRECOMPILED=<your_home_directory>/Android/hifi_externals
HIFI_ANDROID_KEYSTORE=<key_store_directory>/<keystore_name>.jks
HIFI_ANDROID_KEYSTORE_PASSWORD=<password>
HIFI_ANDROID_KEY_ALIAS=<key_alias>
HIFI_ANDROID_KEY_PASSWORD=<key_passwords>

Note, do not use $HOME for the path. It must be a fully qualified path name. Also, be sure to use forward slashes in your path.

If you are building for an Android phone

Add these lines to gradle.properties

SUPPRESS_QUEST_INTERFACE
SUPPRESS_QUEST_FRAME_PLAYER

If you are building for an Oculus Quest

Add these lines to gradle.properties

SUPPRESS_INTERFACE
SUPPRESS_FRAME_PLAYER

The Frame Player for both Android Phone and Oculus Quest is optional, so if you encounter problems with these during your build, you can skip them by adding these lines to gradle.properties

SUPPRESS_FRAME_PLAYER
SUPPRESS_QUEST_FRAME_PLAYER

Clone the repository

git clone https://github.com/overte-org/overte.git

Building & Running

Building Modules

  • Open Android Studio
  • Choose Open an existing Android Studio project
  • Navigate to the overte repository that had you cloned and choose the android folder and select OK
  • Wait for Gradle to sync (this should take around 20 minutes the first time)
  • If a dialog pops open saying "Plugin Update Recommeded" dialog, do not click update, just click X on the top right to close.
  • In the Project window click on the project you wish to build (i.e. "questInterface") then click Build in the top menu and choose Make Module 'questInterface'
  • By default this will build the "debug" apk, you can change this by opening the Build Variants window along the left side and select other build types such as "release".
  • Your newly build APK should reside in overte\android\apps\questInterface\release (if you chose release).

Running a Module

You are free to use the "adb" command line or other development tools to install (sideload on Quest) your newly built APK, or you can follow the instructions below to load the APK via Android Studio.

  • In the toolbar at the top of Android Studio, next to the green hammer icon, you should see a dropdown menu.
  • You may already see a configuration for the module you are trying to build. If so, select it.
  • Otherwise, select Edit Configurations.

Your configuration should be as follows

  • Type: Android App
  • Module: (you probably want interface or questInterface)

For the interface modules, you also need to select the activity to launch.

For the Android phone interface

  • From the Launch drop down menu, select Specified Activity
  • In the Activity field directly below, put io.highfidelity.hifiinterface.PermissionChecker

For the Oculus Quest interface

  • From the Launch drop down menu, select Specified Activity
  • In the Activity field directly below, put io.highfidelity.questInterface.PermissionsChecker

Note the 's' in PermissionsChecker for the Quest.

Now you are able to run your module! Click the green play button in the top toolbar of Android Studio.

Troubleshooting

To view a more complete debug log,

  • Click the icon with the two overlapping squares in the upper left corner of the tab where the sync is running (hover text says Toggle view)
  • To change verbosity, click File > Settings. Under Build, Execution, Deployment > Compiler you can add command-line flags, as per Gradle documentation

If you encounter CMake issues, try adding the following system environment variable:

With your start menu, search for 'Edit the System Environment Variables' and open it.

  • Click on 'Advanced' tab, then 'Environment Variables'
  • Select 'New' under System variables
  • Set "Variable name" to QT_CMAKE_PREFIX_PATH
  • Set "Variable value" to the directory that your android build placed the CMake 3.6.4 library CMake directory (i.e. android\qt\lib\cmake).

Some things you can try if you want to do a clean build

  • Delete the build and .externalNativeBuild folders from the folder for each module you're building (for example, overte/android/apps/interface)
  • If you have set your HIFI_VCPKG_ROOT environment variable, delete the contents of that directory; otherwise, delete AppData/Local/Temp/hifi
  • In Android Studio, click File > Invalidate Caches / Restart and select Invalidate and Restart

If you see lots of "couldn't acquire lock" errors,

  • Open Task Manager and close any running Clang / Gradle processes