Skip to main content

Building for Meta Quest

This document describes the process to build Ocean projects for Meta Quest devices. It covers:

  1. General requirements
  2. Building required third-party libraries
  3. Building Quest demo apps that come with Ocean

1 Prerequisites​

To build the project, you need to satisfy the following prerequisites:

General build prerequisites​

Please refer to the main page for general build prerequisites.

  • Python 3.8 or higher

Android Setup​

Please refer to the instructions to build Ocean for Android for the Android setup.

Quest setup​

Activate Developer Mode (Required)

To install, run, and debug native apps on your Quest device, it is essential to enable Developer Mode first. This mode allows you to directly communicate with your device, essential for development and testing purposes.

Please follow the detailed guide provided by Oculus to enable Developer Mode on your Quest: Mobile Device Setup. Once your Quest is in Developer Mode, you can connect it to your computer via a USB cable. To verify that your device is properly set up and recognized, use the following adb command:

adb devices

This command should list your Quest device, indicating that it is ready for development activities. If your device does not appear, ensure that your USB drivers are correctly installed and that the USB cable is functioning properly.

Oculus (OVR) Platform SDK (Optional)

While this SDK is optional some of the Ocean demo apps for Quest require this setup, for example Microphone demo for Quest devices.

  • Download the most recent SDK: Oculus Platform SDK
  • Uncompress the archive and move the uncompressed directory to its destination folder
  • Define the following environment variable:
    • OVRPlatformSDK_ROOT - points to root directory of unzipped Oculus Platform SDK files, e.g. {'{$HOME}'}/Downloads/ovr_platform_sdk_XX.Y where XX.Y needs to be replaced with the version that was downloaded.
  • When setup properly, following files should exist in the directory structure located at {'{$OVRPlatformSDK_ROOT}'}:
    • {'{$OVRPlatformSDK_ROOT}'}/Android/libs/arm64-v8a/libovrplatformloader.so
    • {'{$OVRPlatformSDK_ROOT}'}/Include/OVR_Platform.h (and other header files in the same directory)

2 Building the third-party libraries​

Please refer to the instructions for Android for details about building the required third-party libraries. For Quest, you only need to build for Android ARM64.

cd /path/to/ocean

# Build third-party libraries for Android ARM64 (sufficient for Quest)
python build/python/build_ocean_3rdparty.py --target android_arm64

On Windows:

cd \path\to\ocean
python build/python/build_ocean_3rdparty.py --target android_arm64

This will build the third-party libraries with the following default settings which are compatible with Quest:

  • Architecture: arm64
  • Linking type: static
  • Build config: debug and release

Once the build is complete, the installed libraries can be found in ocean_3rdparty/install/. Headers are in <lib>/h/android/ and libraries in <lib>/lib/android_arm64_static_debug/ and .../android_arm64_static_release/.

Run python build/python/build_ocean_3rdparty.py --help to see all available options.

Note: The build system displays a real-time TUI with progress for all parallel build jobs. Use --log-level verbose to see detailed build output instead.

Note: On a Windows build host, it is advisable to use --output-dir C:\ocean_3rdparty to place output directories close to the root of a filesystem due to Windows limitations on path lengths.

2.1 Building Ocean for Quest (Optional)​

If you want to build Ocean libraries for Quest separately (not via Gradle), you can use the build script with the --quest flag:

cd /path/to/ocean
python build/python/build_ocean.py --quest --third-party-layout python

On Windows:

cd \path\to\ocean
python build/python/build_ocean.py --quest --third-party-layout python

This will build Ocean using the Quest-specific CMake presets which configure additional Quest extensions.

3 Building Quest demo apps that come with Ocean​

Please refer to the builds steps in the instructions for Android for details about building Ocean Android apps with Gradle.

The Gradle build configurations for Quest demo apps can be found under the directory structure at build/gradle/application/ocean/demo/platform/meta/quest/openxr/.

To build Quest demo apps, first build the required third-party libraries as described above. Then find the Gradle configuration of a Quest app that you want to build, for example build/gradle/application/ocean/demo/platform/meta/quest/openxr/renderer/quest/app/build.gradle.kts.

To build the APK, run "gradlew" from the directory in the manner examplified below.

# Adjust this to your location of the third-party libraries
export OCEAN_THIRDPARTY_PATH="{'{$HOME}'}/install_ocean_thirdparty_android

cd /path/to/ocean/build/gradle/application/ocean/demo/platform/meta/quest/openxr/fingerdistance/quest

# Build the APK of the application
./gradlew build

# Install debug build of the app
adb install app/build/outputs/apk/debug/app-debug.apk

# Install release build of the app
adb install app/build/outputs/apk/release/app-release.apk

The don the device and start the app from the menu. Log messages can be displayed using:

adb logcat -s Ocean

Additional Notes​

Not all Android apps provided with Ocean have been tested on Quest devices.

Building an Android app for Quest devices may require editing the app's Gradle configuration to lower the minimum Android SDK version requirement. Installation of apps may fail if minSdk value set for the app is higher than Android SDK version on the device (e.g. minSdk = 32 to be able to run on Quest 3 with system update from 2023.06.30).

See example Gradle configuration snippet below:

defaultConfig {
  applicationId = "com.meta.ocean.app.demo.platform.android.pixelformats.android"
  minSdk = 32
tip

This documentation is also available on GitHub.