Horizon OS NSDK project setup

• Header files: C API declarations to include at compile time, such as <horizonos/versioning.h> and <horizonos/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 HzOS.

• Option A: Gradle dependency (recommended). The Horizon 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 HzOS NSDK.

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

[versions]
horizon-os-nsdk = "204"    # Replace with latest Horizon OS NSDK version

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

dependencies {
    implementation(libs.horizon.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 Horizon OS NSDK package automatically.
find_package(horizon-os-nsdk REQUIRED CONFIG)

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

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

1. Configure the Maven Central repository in your project as described in Step A1: Add the Maven Central repository.
2. Declare the Horizon OS NSDK dependency as described in Step A2: Add the Horizon 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.

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

cmake_minimum_required(VERSION 3.22.1)
project("horizon_os_nsdk")

# Declare the Horizon 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 Horizon OS NSDK library sub-project.
# Path is relative to this CMakeLists.txt (app/src/main/cpp/).
add_subdirectory(../../../../horizon_os_nsdk_lib horizon_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:horizonos="http://schemas.horizonos/sdk"
    xmlns:tools="http://schemas.android.com/tools">

    <horizonos:uses-horizonos-sdk
        horizonos:minSdkVersion="66"
        horizonos:targetSdkVersion="204" />

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

adb shell getprop ro.horizonos.version.sdk

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

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

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

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

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


    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val version = getHzOSVersion()
        enableEdgeToEdge()
        setContent {
            MyappTheme {
                Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
                    Greeting(
                        name = "HzOS 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(horizon-os-nsdk REQUIRED CONFIG) is present in your CMakeLists.txt and you are linking against horizon-os-nsdk::hzos (not bare hzos). The headers are included transitively.
• Option B:horizon_os_nsdk_lib/CMakeLists.txt exists and correctly declares the hzos.meta imported library. The stub .so is present at horizon_os_nsdk_lib/stubs/arm64-v8a/libhzos.meta.so. Your app’s CMakeLists.txt includes add_subdirectory for horizon_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 horizon_os_nsdk_lib/include/horizonos/. The target_include_directories in horizon_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 HzOS version meets or exceeds the value of horizonos:minSdkVersion declared in your app’s AndroidManifest.xml.
• <horizonos:uses-horizonos-sdk> is declared in your manifest. Without it, the Meta Horizon Store may ship your binary to devices that don’t meet your minimum HzOS 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
}