Address C12+C14: MetalRT stub pattern for public-repo compile

The MetalRT engine (libmetalrt_engine.a + .metallib shaders) is a
closed-source private dependency. Public repo users could not compile
with RAC_BACKEND_METALRT=ON without access to the private engine.
This change introduces a stub pattern that lets the public repo compile
cleanly, and fails with a clear runtime error when MetalRT inference
is requested without the engine binary installed.

Pattern (extensible to future private backends, e.g. Qualcomm NPU):

1. Compile-time (CMake):
   New RAC_METALRT_ENGINE_AVAILABLE option. OFF by default (public):
   the stub header + stub .c file under src/backends/metalrt/stubs/
   are compiled in, every metalrt_* symbol resolves to a no-op.
   ON (internal): the real private metalrt_c_api.h from METALRT_ROOT
   is used and libmetalrt_engine.a is linked with find_library REQUIRED
   (configure fails hard if engine claimed-available but missing,
   matching llamacpp/onnx behavior).

2. Fixes the C12 orphan-target concern: rac_backend_metalrt is now an
   OBJECT library folded into rac_commons via
     target_sources(rac_commons PRIVATE $<TARGET_OBJECTS:rac_backend_metalrt>)
   mirroring the RAG pattern. No separate librac_backend_metalrt.a to
   distribute — wrappers ride in librac_commons.a (and RACommons
   xcframework on iOS); engine + tokenizers ship separately in
   RABackendMetalRT.xcframework when the authorized developer enables
   it.

3. Runtime: rac_backend_metalrt_register() on a stub build logs a
   clear warning and skips provider registration entirely. The service
   registry then returns BACKEND_NOT_FOUND at loadModel call sites,
   which Swift maps to SDKError.componentNotAvailable. No crashes, no
   silent no-ops. metalrt_can_handle also short-circuits to RAC_FALSE
   as belt-and-suspenders.

4. New error code RAC_ERROR_BACKEND_UNAVAILABLE = -604 in the backend
   range (-600..-699) for callers that need to distinguish "backend
   not found" from "backend compiled as stub". Error message added.

5. build-ios.sh: passes -DRAC_METALRT_ENGINE_AVAILABLE=ON whenever
   --backend metalrt is selected, so the internal MetalRT iOS build
   continues to work end-to-end (RACommons xcframework with real
   wrappers + RABackendMetalRT xcframework with engine + tokenizers).

Files:
- src/backends/metalrt/stubs/metalrt_c_api.h (new, public stub)
- src/backends/metalrt/stubs/metalrt_c_api_stub.c (new, no-op)
- src/backends/metalrt/CMakeLists.txt (two-branch + OBJECT)
- CMakeLists.txt (fold rac_backend_metalrt into rac_commons)
- src/backends/metalrt/rac_backend_metalrt_register.cpp
  (short-circuit can_handle + register on stub builds)
- include/rac/core/rac_error.h + src/core/rac_error.cpp
  (RAC_ERROR_BACKEND_UNAVAILABLE)
- scripts/build-ios.sh (pass RAC_METALRT_ENGINE_AVAILABLE=ON)

Verified: all 5 MetalRT wrapper .cpp files compile cleanly against the
stub header with clang -std=c++20 -DRAC_METALRT_ENGINE_AVAILABLE=0.
Default build (RAC_BUILD_BACKENDS=OFF) still configures cleanly.

When the MetalRT project is open-sourced or moved into a private SPM
binary pipeline, the only change needed is flipping
RAC_METALRT_ENGINE_AVAILABLE=ON plus wiring the binary fetch — the
stub and wrappers stay untouched.

Author: sanchitmonga22

examples/ios/RunAnywhereAI/Package.resolved

@@ -507,8 +507,32 @@ if(RAC_BUILD_BACKENDS)
     endif()
 
     if(RAC_BACKEND_METALRT AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/src/backends/metalrt/CMakeLists.txt")
-        message(STATUS "  - MetalRT backend")
+        message(STATUS "  - MetalRT backend — folded into rac_commons")
         add_subdirectory(src/backends/metalrt)
+
+        # MetalRT is an OBJECT library. Fold its compiled objects into
+        # rac_commons so there is no separate rac_backend_metalrt artifact
+        # to distribute — mirrors how RAG is integrated. Public builds ship
+        # stub implementations; engine-enabled builds link the private
+        # libmetalrt_engine.a via RAC_METALRT_ENGINE_LIB propagated from
+        # the subdirectory.
+        target_sources(rac_commons PRIVATE $<TARGET_OBJECTS:rac_backend_metalrt>)
+
+        # Apple frameworks are needed wherever the wrappers are compiled.
+        if(APPLE)
+            target_link_libraries(rac_commons PUBLIC
+                "-framework Metal"
+                "-framework Foundation"
+                "-framework Accelerate"
+            )
+        endif()
+
+        # If the engine is available, link the private static lib onto
+        # rac_commons so the OBJECT target's unresolved metalrt_* symbols
+        # resolve in the final archive.
+        if(RAC_METALRT_ENGINE_LIB)
+            target_link_libraries(rac_commons PUBLIC ${RAC_METALRT_ENGINE_LIB})
+        endif()
     endif()
 
     if(RAC_BACKEND_RAG AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/src/features/rag/CMakeLists.txt")

sdk/runanywhere-commons/CMakeLists.txt

@@ -365,6 +365,8 @@ extern "C" {
 #define RAC_ERROR_BACKEND_INIT_FAILED ((rac_result_t) - 602)
 /** Backend busy */
 #define RAC_ERROR_BACKEND_BUSY ((rac_result_t) - 603)
+/** Backend unavailable: backend compiled as stub, engine binary not installed */
+#define RAC_ERROR_BACKEND_UNAVAILABLE ((rac_result_t) - 604)
 /** Invalid handle */
 #define RAC_ERROR_INVALID_HANDLE ((rac_result_t) - 610)
 

sdk/runanywhere-commons/include/rac/core/rac_error.h

@@ -204,6 +204,7 @@ build_macos() {
                 ;;
             metalrt)
                 BACKEND_FLAGS="$BACKEND_FLAGS -DRAC_BACKEND_LLAMACPP=OFF -DRAC_BACKEND_ONNX=OFF -DRAC_BACKEND_WHISPERCPP=OFF -DRAC_BACKEND_METALRT=ON"
+                BACKEND_FLAGS="$BACKEND_FLAGS -DRAC_METALRT_ENGINE_AVAILABLE=ON"
                 BACKEND_FLAGS="$BACKEND_FLAGS -DMETALRT_ROOT=${METALRT_ROOT}"
                 ;;
             all|*)
@@ -311,6 +312,7 @@ build_platform() {
                 ;;
             metalrt)
                 BACKEND_FLAGS="$BACKEND_FLAGS -DRAC_BACKEND_LLAMACPP=OFF -DRAC_BACKEND_ONNX=OFF -DRAC_BACKEND_WHISPERCPP=OFF -DRAC_BACKEND_METALRT=ON"
+                BACKEND_FLAGS="$BACKEND_FLAGS -DRAC_METALRT_ENGINE_AVAILABLE=ON"
                 BACKEND_FLAGS="$BACKEND_FLAGS -DMETALRT_ROOT=${METALRT_ROOT}"
                 if [[ -n "${METALRT_IOS_BUILD_DIR}" ]]; then
                     BACKEND_FLAGS="$BACKEND_FLAGS -DMETALRT_LIB_DIR=${METALRT_IOS_BUILD_DIR}"

sdk/runanywhere-commons/scripts/build-ios.sh

@@ -1,56 +1,94 @@
 # MetalRT Backend — Apple-only (iOS/macOS)
-# Requires pre-built libmetalrt_engine.a and metalrt_c_api.h
+#
+# The MetalRT engine (libmetalrt_engine.a + metalrt_c_api.h) is a private,
+# closed-source dependency. This CMakeLists supports two modes:
+#
+#   1) Engine NOT available (default in the public repo):
+#      - RAC_METALRT_ENGINE_AVAILABLE is OFF.
+#      - The public stub header and stub source under stubs/ are compiled in.
+#      - Every metalrt_* symbol resolves to a no-op returning a sentinel.
+#      - The public repo links cleanly. At runtime, the wrappers + vtable
+#        registration short-circuit to RAC_ERROR_BACKEND_UNAVAILABLE before
+#        invoking these stubs, so loadModel(..., framework: .metalrt) returns
+#        a clean error instead of a crash.
+#
+#   2) Engine IS available (internal / authorized builds):
+#      - RAC_METALRT_ENGINE_AVAILABLE=ON.
+#      - METALRT_ROOT must point at the private MetalRT project.
+#      - The real metalrt_c_api.h from METALRT_ROOT/src is used; stubs are
+#        skipped. libmetalrt_engine.a is linked via find_library (REQUIRED).
+#      - Configure fails hard if the engine is claimed-available but missing,
+#        consistent with how llamacpp/onnx handle missing deps.
 
-set(METALRT_SOURCES
+option(RAC_METALRT_ENGINE_AVAILABLE
+    "Link the private MetalRT engine (libmetalrt_engine.a). OFF = compile stubs only."
+    OFF)
+
+set(METALRT_WRAPPER_SOURCES
     rac_llm_metalrt.cpp
     rac_stt_metalrt.cpp
     rac_tts_metalrt.cpp
     rac_vlm_metalrt.cpp
     rac_backend_metalrt_register.cpp
 )
 
-# MetalRT pre-built library location (set by parent or via -DMETALRT_ROOT=...)
-if(NOT DEFINED METALRT_ROOT)
-    # Default: assume MetalRT is sibling to runanywhere-sdks
-    set(METALRT_ROOT "${CMAKE_SOURCE_DIR}/../../../MetalRT" CACHE PATH "Path to MetalRT project root")
-endif()
-
-set(METALRT_INCLUDE_DIR "${METALRT_ROOT}/src" CACHE PATH "Path to metalrt_c_api.h")
-
-# Find the pre-built static library
-if(DEFINED METALRT_LIB_DIR)
-    set(_metalrt_lib_dir "${METALRT_LIB_DIR}")
-else()
-    set(_metalrt_lib_dir "${METALRT_ROOT}/build")
-endif()
-
-add_library(rac_backend_metalrt STATIC ${METALRT_SOURCES})
+# Folded into rac_commons as an OBJECT library — no separate artifact to ship.
+add_library(rac_backend_metalrt OBJECT ${METALRT_WRAPPER_SOURCES})
 
 target_include_directories(rac_backend_metalrt PRIVATE
     ${CMAKE_SOURCE_DIR}/include
     ${CMAKE_CURRENT_SOURCE_DIR}
-    ${METALRT_INCLUDE_DIR}
 )
 
 target_compile_definitions(rac_backend_metalrt PRIVATE RAC_METALRT_BUILDING)
 
-# Link MetalRT static library
-# NO_CMAKE_FIND_ROOT_PATH: the engine is built locally, not inside the iOS SDK sysroot
-find_library(METALRT_ENGINE_LIB
-    NAMES metalrt_engine
-    PATHS ${_metalrt_lib_dir}
-    NO_DEFAULT_PATH
-    NO_CMAKE_FIND_ROOT_PATH
-)
+if(RAC_METALRT_ENGINE_AVAILABLE)
+    # ------------------------------------------------------------------
+    # Real engine path — MetalRT project must be present and built.
+    # ------------------------------------------------------------------
+    if(NOT DEFINED METALRT_ROOT)
+        # Default: assume MetalRT is sibling to runanywhere-sdks
+        set(METALRT_ROOT "${CMAKE_SOURCE_DIR}/../../../MetalRT" CACHE PATH "Path to MetalRT project root")
+    endif()
+
+    set(METALRT_INCLUDE_DIR "${METALRT_ROOT}/src" CACHE PATH "Path to metalrt_c_api.h")
+
+    if(DEFINED METALRT_LIB_DIR)
+        set(_metalrt_lib_dir "${METALRT_LIB_DIR}")
+    else()
+        set(_metalrt_lib_dir "${METALRT_ROOT}/build")
+    endif()
+
+    # NO_CMAKE_FIND_ROOT_PATH: the engine is built locally, not inside the iOS sysroot.
+    find_library(METALRT_ENGINE_LIB
+        NAMES metalrt_engine
+        PATHS ${_metalrt_lib_dir}
+        NO_DEFAULT_PATH
+        NO_CMAKE_FIND_ROOT_PATH
+        REQUIRED
+    )
+
+    message(STATUS "MetalRT: engine AVAILABLE, linking ${METALRT_ENGINE_LIB}")
+    target_include_directories(rac_backend_metalrt PRIVATE ${METALRT_INCLUDE_DIR})
+    target_compile_definitions(rac_backend_metalrt PRIVATE RAC_METALRT_ENGINE_AVAILABLE=1)
 
-if(METALRT_ENGINE_LIB)
-    target_link_libraries(rac_backend_metalrt PRIVATE ${METALRT_ENGINE_LIB})
-    message(STATUS "MetalRT: Found libmetalrt_engine at ${METALRT_ENGINE_LIB}")
+    # The parent CMakeLists folds this target's objects into rac_commons; the
+    # engine .a needs to be linked onto rac_commons from the parent scope so
+    # that the OBJECT target's undefined symbols resolve in the final archive.
+    set(RAC_METALRT_ENGINE_LIB ${METALRT_ENGINE_LIB} PARENT_SCOPE)
 else()
-    message(WARNING "MetalRT: libmetalrt_engine.a not found in ${_metalrt_lib_dir} — will need to be linked by the consuming app")
+    # ------------------------------------------------------------------
+    # Stub path — public-repo default. Compile the stub .c file so every
+    # metalrt_* symbol resolves to a no-op. No external dependency.
+    # ------------------------------------------------------------------
+    message(STATUS "MetalRT: engine not available — compiling stubs")
+    target_sources(rac_backend_metalrt PRIVATE stubs/metalrt_c_api_stub.c)
+    target_include_directories(rac_backend_metalrt PRIVATE stubs)
+    target_compile_definitions(rac_backend_metalrt PRIVATE RAC_METALRT_ENGINE_AVAILABLE=0)
 endif()
 
-# Apple frameworks
+# Apple frameworks are always needed on this target (the wrappers reference
+# Metal-framework types in some paths even without the engine).
 target_link_libraries(rac_backend_metalrt PRIVATE
     "-framework Metal"
     "-framework Foundation"

sdk/runanywhere-commons/src/backends/metalrt/CMakeLists.txt

@@ -337,6 +337,15 @@ MetalRTRegistryState& get_state() {
 rac_bool_t metalrt_can_handle(const rac_service_request_t* request, void* /*user_data*/) {
     if (!request) return RAC_FALSE;
 
+#if !defined(RAC_METALRT_ENGINE_AVAILABLE) || RAC_METALRT_ENGINE_AVAILABLE == 0
+    // Stub build: the private MetalRT engine binary is not linked. Refuse to
+    // handle any request so the service registry surfaces BACKEND_NOT_FOUND
+    // at the loadModel call site instead of silently dispatching to stubs.
+    (void)request;
+    RAC_LOG_DEBUG(LOG_CAT,
+                  "can_handle: NO (MetalRT engine not available — stub build)");
+    return RAC_FALSE;
+#else
     if (request->framework == RAC_FRAMEWORK_METALRT) {
         RAC_LOG_DEBUG(LOG_CAT, "can_handle: YES (framework=METALRT)");
         return RAC_TRUE;
@@ -345,6 +354,7 @@ rac_bool_t metalrt_can_handle(const rac_service_request_t* request, void* /*user
     RAC_LOG_DEBUG(LOG_CAT, "can_handle: NO (framework=%d, want METALRT=%d)",
                   static_cast<int>(request->framework), RAC_FRAMEWORK_METALRT);
     return RAC_FALSE;
+#endif
 }
 
 // =============================================================================
@@ -488,6 +498,18 @@ rac_result_t rac_backend_metalrt_register(void) {
         return RAC_ERROR_MODULE_ALREADY_REGISTERED;
     }
 
+#if !defined(RAC_METALRT_ENGINE_AVAILABLE) || RAC_METALRT_ENGINE_AVAILABLE == 0
+    // Stub build: the private MetalRT engine binary is not linked. Log clearly
+    // and skip provider registration entirely so the registry never dispatches
+    // a model load into no-op stubs.
+    RAC_LOG_WARNING(LOG_CAT,
+                    "MetalRT backend compiled without engine binary — skipping "
+                    "provider registration. loadModel(..., framework: .metalrt) "
+                    "will fail with BACKEND_NOT_FOUND until the engine is installed.");
+    state.registered = true;
+    return RAC_SUCCESS;
+#endif
+
     // Register module
     rac_module_info_t module_info = {};
     module_info.id = state.module_id;