Meta VR OS NSDK project setup

• Header files: C API declarations to include at compile time, such as <metavr/versioning.h> and <metavr/common.h>.
• Stub shared library (libhzos.meta.so): a minimal shared object that provides symbol definitions for the linker at build time. It contains no real implementation.

• Android Studio Ladybug (2024.2) or newer
• Android Gradle Plugin 8.9 or higher
• CMake 3.22.1 or higher (installable through Android Studio SDK Manager)
  • To install: Go to Tools > SDK Manager > SDK Tools and check CMake.
• Android NDK (installable through Android Studio SDK Manager)
  • To Install: In the same SDK Tools tab, check NDK (Side by side).
• Gradle 8.13 or higher
• A physical Meta Quest device running Horizon OS.

• Option A: Gradle dependency (recommended). The Meta VR OS NSDK AAR is published on Maven Central with Prefab metadata. Gradle automatically exposes the native headers and stub library to CMake. This is the simplest path with fewer manual steps.
• Option B: Manual setup. Download the AAR, extract headers and the stub library into a local directory, and configure CMake by hand. Use this approach for offline development or when you need to customize the library layout.

1. Open Android Studio and select File > New > New Project.
2. Under the Phone and Tablet category, choose Empty Activity. Quest devices run Android, so you can use standard Android templates. Later steps walk you through adding native C++ and CMake configuration.
3. Set:
   • Language: Kotlin (or Java)
   • Minimum SDK: API 34
   • Build configuration language: Kotlin DSL (build.gradle.kts)
4. Click Finish.
5. Note your project name and package name. You’ll use them in the CMake configuration and JNI function signatures in later steps. This guide uses myapp and com.example.myapp as examples; replace them with your actual values.
6. Once the project is created, follow Option A or Option B below to integrate the Meta VR OS NSDK.

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()   // Required for Meta VR OS NSDK
    }
}

[versions]
metavr-os-nsdk = "207"    # Replace with latest Meta VR OS NSDK version

[libraries]
metavr-os-nsdk = { group = "com.meta.metavr", name = "metavr-os-nsdk", version.ref = "metavr-os-nsdk" }

dependencies {
    implementation(libs.metavr.os.nsdk)
}

android {
    // ... existing config ...

    buildFeatures {
        prefab = true
    }

    defaultConfig {
        // Only arm64-v8a is supported on Meta Quest devices.
        ndk {
            abiFilters.clear()
            abiFilters += listOf("arm64-v8a")
        }
    }

    // Exclude the stub .so from the APK. The real library is on the device.
    packaging {
        jniLibs {
            excludes += listOf("**/libhzos.meta.so")
        }
    }

    externalNativeBuild {
        cmake {
            path = file("src/main/cpp/CMakeLists.txt")
            version = "3.22.1"
        }
    }
}

cmake_minimum_required(VERSION 3.22.1)
project("myapp")

# Prefab exposes the Meta VR OS NSDK package automatically.
find_package(metavr-os-nsdk REQUIRED CONFIG)

add_library(${CMAKE_PROJECT_NAME} SHARED
    nsdk-example.cpp
)

target_link_libraries(${CMAKE_PROJECT_NAME}
    android
    log
    metavr-os-nsdk::hzos
)

target_link_libraries(${CMAKE_PROJECT_NAME}
    android
    log
    metavr-os-nsdk::metavr_headers
)

• A target includes the headers but calls no API, such as a shared interface layer or a bindings generator. Linking the stub there adds a dependency the target has no use for.
• You build a variant for another ABI. The AAR carries the stub for arm64-v8a alone, so metavr-os-nsdk::hzos fails to resolve in an x86_64 variant. The headers resolve for every ABI.
• You resolve the API at runtime. Linking metavr-os-nsdk::hzos records libhzos.meta.so as a load-time dependency of your library, so System.loadLibrary fails on any device that does not supply that library. Linking metavr-os-nsdk::metavr_headers instead takes the declarations from the headers and leaves you to resolve the entry points through dlopen and dlsym, so your app starts and takes a fallback path when the library is absent. Meta VR OS NSDK entry points are C functions, so dlsym finds them under the names the headers declare.

1. Configure the Maven Central repository in your project as described in Step A1: Add the Maven Central repository.
2. Declare the Meta VR OS NSDK dependency as described in Step A2: Add the Meta VR OS NSDK dependency.
3. Copy the .aar file to your project. Rename the extension from .aar to .zip and extract it to get the headers and stub library.

metavr_os_nsdk_lib/
├── CMakeLists.txt
├── include/
│   └── metavr/
│       ├── common.h
│       └── versioning.h
│       └── ...
└── stubs/
    └── arm64-v8a/
        └── libhzos.meta.so    (stub, build-time only)

cmake_minimum_required(VERSION 3.22.1)
project("metavr_os_nsdk")

# Declare the Meta VR OS NSDK stub as an imported shared library.
add_library(hzos.meta SHARED IMPORTED GLOBAL)

# Point to the ABI-specific stub.
set_target_properties(hzos.meta PROPERTIES
    IMPORTED_LOCATION ${CMAKE_CURRENT_SOURCE_DIR}/stubs/${ANDROID_ABI}/libhzos.meta.so
)

# Expose the NSDK headers to consumers.
# SYSTEM suppresses compiler warnings originating from these headers.
target_include_directories(hzos.meta SYSTEM
    INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/include
)

cmake_minimum_required(VERSION 3.22.1)
project("myapp")

# Import the Meta VR OS NSDK library sub-project.
# Path is relative to this CMakeLists.txt (app/src/main/cpp/).
add_subdirectory(../../../../metavr_os_nsdk_lib metavr_os_nsdk_lib_binary)

add_library(${CMAKE_PROJECT_NAME} SHARED
    nsdk-example.cpp
)

target_link_libraries(${CMAKE_PROJECT_NAME}
    android
    log
    hzos.meta
)

android {
    // ... existing config ...

    defaultConfig {
        // Only arm64-v8a is supported on Meta Quest devices.
        ndk {
            abiFilters.clear()
            abiFilters += listOf("arm64-v8a")
        }
    }

    // Exclude the stub .so from the APK. The real library is on the device.
    packaging {
        jniLibs {
            excludes += listOf("**/libhzos.meta.so")
        }
    }

    externalNativeBuild {
        cmake {
            path = file("src/main/cpp/CMakeLists.txt")
            version = "3.22.1"
        }
    }
}

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:metavr="http://schemas.meta.com/metavr-sdk"
    xmlns:tools="http://schemas.android.com/tools">

    <metavr:uses-metavr-sdk
        metavr:minSdkVersion="66"
        metavr:targetSdkVersion="207" />

    <application ...>
        <!-- your activities -->
    </application>
</manifest>

adb shell getprop ro.vros.build.version

# After building, check the merged manifest:
cat app/build/intermediates/merged_manifests/debug/AndroidManifest.xml | grep metavr

#include <jni.h>
#include <string>
#include <metavr/versioning.h>

extern "C" JNIEXPORT jstring JNICALL
Java_com_example_myapp_MainActivity_getMetaVrOsSdkVersion(
        JNIEnv* env,
        jobject /* this */) {
    std::string version = std::to_string(MvrOS_getVersion());
    return env->NewStringUTF(version.c_str());
}

class MainActivity : ComponentActivity() {
    external fun getMetaVrOsSdkVersion(): String

    companion object {
        init {
            System.loadLibrary("myapp")
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val version = getMetaVrOsSdkVersion()
        enableEdgeToEdge()
        setContent {
            MyappTheme {
                Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
                    Greeting(
                        name = "Meta VR OS SDK Version: $version",
                        modifier = Modifier.padding(innerPadding)
                    )
                }
            }
        }
    }
}

• Make sure prefab = true is set under buildFeatures in your app/build.gradle.kts.
• Run File > Sync Project with Gradle Files and wait for sync to complete before building.
• Verify that the dependency version in libs.versions.toml matches an available release on Maven Central.
• Check that mavenCentral() is listed in your settings.gradle.kts repositories.

• Option A:find_package(metavr-os-nsdk REQUIRED CONFIG) is present in your CMakeLists.txt and you are linking against metavr-os-nsdk::hzos (not bare hzos). The headers are included transitively. metavr-os-nsdk::metavr_headers on its own supplies the headers and no symbols, so a target that calls the API needs metavr-os-nsdk::hzos.
• Option B:metavr_os_nsdk_lib/CMakeLists.txt exists and correctly declares the hzos.meta imported library. The stub .so is present at metavr_os_nsdk_lib/stubs/arm64-v8a/libhzos.meta.so. Your app’s CMakeLists.txt includes add_subdirectory for metavr_os_nsdk_lib and lists hzos.meta in target_link_libraries.

• Option A: Gradle sync completed successfully and prefab = true is enabled. The find_package call automatically sets up include paths.
• Option B: The headers exist under metavr_os_nsdk_lib/include/metavr/. The target_include_directories in metavr_os_nsdk_lib/CMakeLists.txt points to the correct path.

• Missing System.loadLibrary call: Make sure your activity’s companion object or static block loads the library.
• Wrong library name: The name passed to System.loadLibrary must match the project() name in your app’s CMakeLists.txt (without the lib prefix and .so suffix).
• ABI mismatch: Make sure abiFilters is set to arm64-v8a and you’re running on a real Quest device (not an x86 emulator).

• packaging.jniLibs.excludes includes "**/libhzos.meta.so" in your build.gradle.kts.
• The device’s Horizon OS version meets or exceeds the value of metavr:minSdkVersion declared in your app’s AndroidManifest.xml.
• <metavr:uses-metavr-sdk> is declared in your manifest. Without it, the Meta Horizon Store may ship your binary to devices that don’t meet your minimum Horizon OS version, producing this symptom in the field. Sideloaded builds are unaffected — the element is not enforced at install or runtime.

• Install CMake 3.22.1 or higher through Tools > SDK Manager > SDK Tools > CMake.
• Make sure the cmake.version in your build.gradle.kts matches an installed version.

android {
    ndkVersion = "27.0.12077973"   // Use an NDK version already installed
}