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.

• CMake 3.25 or higher is required (for CMake preset support)

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, the default build parameters are sufficient.

Linux/macOS

cd /path/to/ocean
./build/cmake/build_thirdparty_android.sh

Windows (PowerShell)

cd \path\to\ocean
.\build\cmake\build_thirdparty_android.ps1

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

• Android ABI: arm64-v8a
• Linking type: static
• Build config: debug and release

Once the build is complete, the compiled binaries can be found in bin/cmake/3rdparty/android/arm64_static_debug and .../android/arm64_static_release.

The build script can be customized if needed. For example, to specify a different Android SDK version:

Linux/macOS

cd /path/to/ocean
./build/cmake/build_thirdparty_android.sh -c debug,release -l static -b "{'{$HOME}'}/build_ocean_thirdparty" -i "{'{$HOME}'}/install_ocean_thirdparty" --abi arm64-v8a --sdk android-32

Windows (PowerShell)

cd \path\to\ocean
.\build\cmake\build_thirdparty_android.ps1 -Config debug,release -Link static -Build C:\build_ocean_thirdparty -Install C:\install_ocean_thirdparty -ABI arm64-v8a -Sdk android-32

Run ./build/cmake/build_thirdparty_android.sh --help (or Get-Help .\build\cmake\build_thirdparty_android.ps1 -Detailed on Windows) to see all available options.

Note: By default, the build scripts only display error messages. To see more detailed CMake output, use --log-level STATUS (or -LogLevel STATUS on Windows) for general progress information, or other levels like VERBOSE or DEBUG.

Note: On a Windows build host, it is advisable to place build and install directories close to the root of a filesystem (e.g., C:\build_ocean_thirdparty) due to Windows limitations on path lengths. Exceeding this limit will result in build errors, for example errors about missing files.

2.1 Building Ocean for Quest (Optional)

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

cd /path/to/ocean
./build/cmake/build_ocean.sh --quest

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

On Windows, you can use PowerShell:

cd \path\to\ocean
.\build\cmake\build_ocean.ps1 -Quest

Or using CMake presets directly:

cmake --preset android-quest-static-release -DCMAKE_PREFIX_PATH="{'{$HOME}'}/install_ocean_thirdparty/android/arm64_static_release"
cmake --build --preset android-quest-static-release --target install

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.