react-native-executorch 0.10.0 → 0.10.1

package/android/build.gradle.kts

@@ -53,6 +53,44 @@ fun rneBuildConfig(): Map<*, *> {
 val rneConfig = rneBuildConfig()
 fun rneFlag(key: String): String = if (rneConfig[key] != false) "ON" else "OFF"
 
+/**
+ * The prebuilt ExecuTorch runtime is not in the npm tarball - `package.json`
+ * excludes it and `scripts/download-libs.js` fetches it from the matching
+ * GitHub release in a postinstall hook. When a package manager skips that hook
+ * the install still looks clean and the failure surfaces much later, out of
+ * CMake, blamed on a missing library rather than on the install. Fail here with
+ * the fix instead.
+ */
+fun requireNativeArtifacts() {
+    val libsDir = file("../third-party/android/libs/executorch")
+    val present = libsDir.listFiles()
+        ?.filter { it.isDirectory && it.resolve("libexecutorch.so").exists() }
+        .orEmpty()
+    if (present.isNotEmpty()) return
+
+    throw GradleException(
+        """
+        react-native-executorch is missing its native artifacts:
+
+          ${libsDir.absolutePath}
+
+        They are downloaded by this package's postinstall hook, which your
+        package manager did not run. pnpm 10 and later block dependency build
+        scripts by default ("Ignored build scripts"), and so do
+        `--ignore-scripts` and `npm ci --ignore-scripts`. Re-run the hook:
+
+          pnpm approve-builds react-native-executorch   # pnpm
+          npm rebuild react-native-executorch           # npm
+          node node_modules/react-native-executorch/scripts/download-libs.js
+
+        If you provision the libraries yourself, put them under
+        third-party/android/libs/executorch/<abi>/ before building.
+        """.trimIndent()
+    )
+}
+
+requireNativeArtifacts()
+
 /**
  * ExecuTorch only supports these ABIs. Honor the app's `reactNativeArchitectures`
  * (e.g. Expo passes `-PreactNativeArchitectures=arm64-v8a` for device builds) so
@@ -70,7 +108,12 @@ android {
     compileSdk = (getExtOrDefault("compileSdkVersion", 34) as Number).toInt()
 
     defaultConfig {
-        minSdk = (getExtOrDefault("minSdkVersion", 21) as Number).toInt()
+        // The prebuilt ExecuTorch runtime is compiled against Android API 26 -
+        // `.note.android.ident` in libexecutorch.so, libxnnpack_executorch_backend.so
+        // and libvulkan_executorch_backend.so all read 26 - so an app below that
+        // ships a library its linker is not guaranteed to be able to load. The
+        // default was 21, which let such a build through to fail on the device.
+        minSdk = (getExtOrDefault("minSdkVersion", 26) as Number).toInt()
         targetSdk = (getExtOrDefault("targetSdkVersion", 34) as Number).toInt()
         consumerProguardFiles("consumer-proguard-rules.pro")
 

package/lib/module/fetcher/telemetry.js

@@ -12,7 +12,7 @@ const DOWNLOAD_EVENT_ENDPOINT = 'https://ai.swmansion.com/telemetry/downloads/ap
 // self-referencing import would need package `exports` support in the consuming
 // bundler to load at all. A wrong value here is analytics noise; a failed
 // import would break the bundle.
-const LIB_VERSION = '0.10.0';
+const LIB_VERSION = '0.10.1';
 
 // Anonymous analytics are on by default; apps opt out via setTelemetryEnabled.
 let telemetryEnabled = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-executorch",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "nativeLibsVersion": "0.10.0",
   "description": "An easy way to run AI models in React Native with ExecuTorch",
   "main": "./lib/module/index.js",
@@ -142,7 +142,7 @@
     "react": "*",
     "react-native": "*",
     "react-native-blob-util": "^0.24.0",
-    "react-native-worklets": "^0.10.0"
+    "react-native-worklets": ">=0.10.0 <0.13.0"
   },
   "peerDependenciesMeta": {
     "@kesha-antonov/react-native-background-downloader": {

package/react-native-executorch.podspec

@@ -1,3 +1,4 @@
+require "fileutils"
 require "json"
 
 package = JSON.parse(File.read(File.join(__dir__, "package.json")))
@@ -6,19 +7,59 @@ package = JSON.parse(File.read(File.join(__dir__, "package.json")))
 # Falls back to all features enabled if the file doesn't exist (e.g. a fresh
 # checkout where the native libs were provisioned manually).
 rne_build_config_path = File.join(__dir__, "rne-build-config.json")
-if File.exist?(rne_build_config_path)
-  rne_build_config = JSON.parse(File.read(rne_build_config_path))
-  enable_opencv   = rne_build_config["enableOpencv"]   != false
-  enable_phonemis = rne_build_config["enablePhonemis"] != false
-  enable_xnnpack  = rne_build_config["enableXnnpack"]  != false
-  enable_coreml   = rne_build_config["enableCoreml"]   != false
-  enable_mlx      = rne_build_config["enableMlx"]      != false
-else
-  enable_opencv   = true
-  enable_phonemis = true
-  enable_xnnpack  = true
-  enable_coreml   = true
-  enable_mlx      = true
+rne_build_config =
+  File.exist?(rne_build_config_path) ? JSON.parse(File.read(rne_build_config_path)) : {}
+
+# Every flag reads `!= false`, so an absent file and an absent key both mean
+# enabled. Keep the hash rather than branching on the file: `opencvPod` below
+# is read from it too, and a nil `rne_build_config` there is a NoMethodError.
+enable_opencv   = rne_build_config["enableOpencv"]   != false
+enable_phonemis = rne_build_config["enablePhonemis"] != false
+enable_xnnpack  = rne_build_config["enableXnnpack"]  != false
+enable_coreml   = rne_build_config["enableCoreml"]   != false
+enable_mlx      = rne_build_config["enableMlx"]      != false
+
+# The native artifacts are not in the npm tarball - `package.json` excludes
+# them and `scripts/download-libs.js` fetches them from the matching GitHub
+# release in a postinstall hook. When a package manager skips that hook the
+# install still looks clean, and so does `pod install`: CocoaPods never checks
+# that a vendored framework exists. The build then fails minutes later with
+#
+#   error: Build input files cannot be found:
+#   '.../XnnpackBackend.xcframework/ios-arm64-simulator/libXnnpackBackend.a'
+#
+# which names neither the cause nor the fix. Fail here instead, while the user
+# is still looking at the install that caused it.
+required_artifacts = { "ExecutorchLib.xcframework" => true }
+required_artifacts["XnnpackBackend.xcframework"] = enable_xnnpack
+required_artifacts["CoreMLBackend.xcframework"]  = enable_coreml
+required_artifacts["MLXBackend.xcframework"]     = enable_mlx
+
+missing = required_artifacts
+  .select { |_, required| required }
+  .keys
+  .map    { |name| File.join(__dir__, "third-party/ios", name) }
+  .reject { |path| File.directory?(path) }
+
+unless missing.empty?
+  # Pod::Informative renders as a plain `[!]` message rather than a backtrace.
+  raise(defined?(Pod::Informative) ? Pod::Informative : StandardError, <<~MESSAGE)
+    react-native-executorch is missing its native artifacts:
+
+    #{missing.map { |path| "  #{path}" }.join("\n")}
+
+    They are downloaded by this package's postinstall hook, which your package
+    manager did not run. pnpm 10 and later block dependency build scripts by
+    default ("Ignored build scripts"), and so do `--ignore-scripts` and
+    `npm ci --ignore-scripts`. Re-run the hook, then `pod install` again:
+
+      pnpm approve-builds react-native-executorch   # pnpm
+      npm rebuild react-native-executorch           # npm
+      node node_modules/react-native-executorch/scripts/download-libs.js
+
+    If you provision the libraries yourself, put them under
+    third-party/ios/ before installing pods.
+  MESSAGE
 end
 
 Pod::Spec.new do |s|
@@ -97,6 +138,34 @@ Pod::Spec.new do |s|
   exclude_files += phonemis_source_files unless enable_phonemis
   s.exclude_files = exclude_files
 
+  # --- Public headers ---
+  # `use_frameworks!` - set directly for Firebase, or through
+  # expo-build-properties' `useFrameworks: "static"` - makes CocoaPods build
+  # this pod as a framework, and Xcode's Headers build phase copies every
+  # *public* header into one flat `Headers/` directory. With no
+  # `public_header_files` every header in `source_files` is public, and the
+  # tree has 21 basenames that occur more than once (`Types.h` in eleven task
+  # directories, `constants.h` in thirteen phonemis ones), so the build fails
+  # at planning with `Multiple commands produce .../Headers/Types.h` before a
+  # single file compiles. See discussion #203.
+  #
+  # Only the Objective-C entry points have to be visible to the app. The C++
+  # headers are reached through the HEADER_SEARCH_PATHS below, so narrowing the
+  # public set costs nothing, and `__tests__/api/podspecPublicHeaders.test.ts`
+  # keeps it collision-free.
+  public_header_files = [
+    "ios/**/*.h",
+  ]
+  # ==============================================================================
+  # LEGACY SUPPORT: include the legacy entry point
+  # (Remove when react-native-executorch/legacy is dropped)
+  # ==============================================================================
+  public_header_files += [
+    "legacy/ios/**/*.h",
+  ]
+  # ==============================================================================
+  s.public_header_files = public_header_files
+
   # --- Preprocessor flags ---
   extra_compiler_flags = []
   extra_compiler_flags << "-DRNE_ENABLE_OPENCV"   if enable_opencv
@@ -143,6 +212,64 @@ Pod::Spec.new do |s|
     'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'x86_64',
   }
 
+  # iOS OpenCV is provided by a CocoaPod (not a downloaded tarball), normally
+  # our own opencv-rne.
+  #
+  # An app can already carry OpenCV through another library, and CocoaPods
+  # refuses to install two vendored frameworks with the same name:
+  #
+  #   [!] The 'Pods-YourApp' target has frameworks with conflicting names:
+  #   opencv2.xcframework
+  #
+  # react-native-fast-opencv is the one this happens with, and wanting both is
+  # reasonable: our inference API with their image transformations. So when it
+  # is installed alongside us we depend on the pod it vendors instead of our
+  # own, which leaves exactly one opencv2 in the project. We only use
+  # `opencv2/core.hpp` and `opencv2/imgproc.hpp`, so any OpenCV 4.x build
+  # serves. Set "opencvPod" in the package.json config block to override the
+  # choice in either direction.
+  external_opencv = false
+  if enable_opencv
+    detected_opencv_pod =
+      if Dir.exist?(File.join(__dir__, "..", "react-native-fast-opencv"))
+        "FastOpenCV-iOS"
+      else
+        "opencv-rne"
+      end
+    opencv_pod = rne_build_config["opencvPod"] || detected_opencv_pod
+
+    if opencv_pod == "opencv-rne"
+      s.dependency "opencv-rne", "~> 4.11.0"
+    else
+      Pod::UI.puts "[react-native-executorch] using #{opencv_pod} for OpenCV " \
+                   "instead of opencv-rne, so the project holds one opencv2" if defined?(Pod::UI)
+      s.dependency opencv_pod
+      external_opencv = true
+    end
+  end
+
+  # Our own OpenCV headers ship under third-party/include and are newer than
+  # what another OpenCV pod vendors: react-native-fast-opencv carries 4.9, and
+  # compiling against ours while linking against theirs fails at link time on
+  # any signature that moved since (cvtColor gained an AlgorithmHint parameter
+  # in 4.10). Whoever provides the binary has to provide the headers, so with
+  # an external OpenCV the include root becomes a mirror of ours with opencv2
+  # left out, and `#include <opencv2/...>` resolves through their framework.
+  mirror_without_opencv = lambda do
+    source = File.join(__dir__, "third-party/include")
+    mirror = File.join(__dir__, "third-party/include-external-opencv")
+    FileUtils.rm_rf(mirror)
+    FileUtils.mkdir_p(mirror)
+    Dir.children(source).each do |entry|
+      next if entry == "opencv2"
+      FileUtils.ln_s(File.join(source, entry), File.join(mirror, entry))
+    end
+    "third-party/include-external-opencv"
+  end
+
+  third_party_include =
+    external_opencv ? mirror_without_opencv.call : "third-party/include"
+
   s.pod_target_xcconfig = {
     "USE_HEADERMAP" => "YES",
     "CLANG_CXX_LANGUAGE_STANDARD" => "c++20",
@@ -158,7 +285,7 @@ Pod::Spec.new do |s|
       # ==============================================================================
       "\"$(PODS_TARGET_SRCROOT)/legacy/cpp\"",
       # ==============================================================================
-      "\"$(PODS_TARGET_SRCROOT)/third-party/include\"",
+      "\"$(PODS_TARGET_SRCROOT)/#{third_party_include}\"",
       "\"$(PODS_TARGET_SRCROOT)/third-party/include/cpuinfo\"",
       "\"$(PODS_TARGET_SRCROOT)/third-party/include/pthreadpool\"",
       "\"$(PODS_TARGET_SRCROOT)/third-party/include/executorch/extension/llm/tokenizers/include\"",
@@ -189,13 +316,23 @@ Pod::Spec.new do |s|
   # resource path. `s.ios.resource` achieves that via CocoaPods' resource copy.
   s.ios.resource = "third-party/ios/libs/executorch/mlx.metallib" if enable_mlx
 
+  # An app that turns on `use_frameworks!` without naming a linkage gets the
+  # default, dynamic - which is what Firebase's own setup instructions show.
+  # CocoaPods then refuses to install at all, because a dynamic framework may
+  # not carry statically linked binaries and opencv-rne vendors one:
+  #
+  #   [!] The 'Pods-YourApp' target has transitive dependencies that include
+  #   statically linked binaries: (.../opencv-rne/opencv2.xcframework)
+  #
+  # Declaring the pod a static framework resolves that without the app having
+  # to spell out `:linkage => :static`, and is inert when the pod is built as a
+  # static library, which is what happens with no `use_frameworks!` at all.
+  s.static_framework = true
+
   # Backend xcframeworks are linked via force_load in OTHER_LDFLAGS (needed to
   # preserve __attribute__((constructor)) backend registrations). Only
   # ExecutorchLib goes in vendored_frameworks to avoid duplicate symbol errors.
   s.ios.vendored_frameworks = ["third-party/ios/ExecutorchLib.xcframework"]
 
-  # iOS OpenCV is provided by the opencv-rne CocoaPod (not a downloaded tarball).
-  s.dependency "opencv-rne", "~> 4.11.0" if enable_opencv
-
   install_modules_dependencies(s)
 end

package/scripts/download-libs.js

@@ -172,32 +172,67 @@ const FEATURE_MAP = {
   tokenizer: { backends: [], libs: [] },
 };
 
-function readUserConfig() {
-  const allOn = () => ({ backends: [...ALL_BACKENDS], libs: [...ALL_LIBS] });
+/**
+ * The `react-native-executorch` block, and the package.json it came from.
+ *
+ * Two places are tried, in order:
+ *
+ *   1. INIT_CWD - where the install was invoked. For a single-app project that
+ *      is the app itself.
+ *   2. Each package.json above this package. In a workspace, `yarn install` is
+ *      run at the root, so INIT_CWD points there and a block in
+ *      `apps/mobile/package.json` would never be seen. When the app keeps its
+ *      own node_modules (pnpm, nohoist), walking up from here lands on the app.
+ *
+ * A hoisted workspace resolves to the root either way, which is where the block
+ * has to live in that layout - there is no way to tell which of several apps a
+ * root install was meant for.
+ * @returns The block and the path of the package.json holding it, or both
+ * `undefined` when no manifest declares one.
+ */
+function findUserConfig() {
+  const candidates = [];
+  const initCwd = process.env.INIT_CWD || process.env.npm_config_local_prefix;
+  if (initCwd) candidates.push(initCwd);
+
+  // `__dirname` is <somewhere>/node_modules/react-native-executorch/scripts.
+  let dir = path.resolve(__dirname, '..', '..', '..');
+  for (let i = 0; i < 6; i++) {
+    if (!candidates.includes(dir)) candidates.push(dir);
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
 
-  // npm/yarn set INIT_CWD to the directory where install was invoked (project root)
-  const projectRoot = process.env.INIT_CWD || process.env.npm_config_local_prefix;
-  if (!projectRoot) {
-    console.warn(
-      '[react-native-executorch] Could not determine project root, enabling all backends + libs.'
-    );
-    return allOn();
+  for (const root of candidates) {
+    const manifest = path.join(root, 'package.json');
+    let parsed;
+    try {
+      parsed = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+    } catch {
+      continue;
+    }
+    if (parsed['react-native-executorch'] !== undefined) {
+      return { config: parsed['react-native-executorch'], manifest };
+    }
   }
+  return { config: undefined, manifest: undefined };
+}
 
-  let rneConfig;
-  try {
-    const userPackageJson = JSON.parse(
-      fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8')
-    );
-    rneConfig = userPackageJson['react-native-executorch'];
-  } catch {
-    console.warn(
-      '[react-native-executorch] Could not read app package.json, enabling all backends + libs.'
+function readUserConfig() {
+  const allOn = () => ({ backends: [...ALL_BACKENDS], libs: [...ALL_LIBS], opencvPod: undefined });
+
+  const { config: rneConfig, manifest } = findUserConfig();
+
+  if (rneConfig === undefined) {
+    console.log(
+      '[react-native-executorch] No `react-native-executorch` block found; enabling all backends + libs.'
     );
     return allOn();
   }
-
-  if (rneConfig === undefined) return allOn();
+  // Which manifest won matters when it is not the one the user edited - the
+  // usual monorepo surprise.
+  console.log(`[react-native-executorch] Read build config from ${manifest}`);
 
   if (rneConfig.extras !== undefined) {
     throw new Error(
@@ -236,10 +271,10 @@ function readUserConfig() {
     }
   }
 
-  return { backends: [...backends], libs: [...libs] };
+  return { backends: [...backends], libs: [...libs], opencvPod: rneConfig.opencvPod };
 }
 
-function writeBuildConfig({ backends, libs }) {
+function writeBuildConfig({ backends, libs, opencvPod }) {
   const config = {
     enableOpencv: libs.includes('opencv'),
     enablePhonemis: libs.includes('phonemis'),
@@ -248,6 +283,10 @@ function writeBuildConfig({ backends, libs }) {
     enableMlx: backends.includes('mlx'),
     enableVulkan: backends.includes('vulkan'),
   };
+  // Which pod provides opencv2 on iOS. Only set when the app asks for a
+  // specific one; otherwise the podspec picks, preferring an OpenCV the app
+  // already carries so two frameworks named opencv2 never meet.
+  if (opencvPod !== undefined) config.opencvPod = opencvPod;
   fs.writeFileSync(
     path.join(PACKAGE_ROOT, 'rne-build-config.json'),
     JSON.stringify(config, null, 2)
@@ -497,4 +536,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { ALL_BACKENDS, ALL_LIBS, FEATURE_MAP };
+module.exports = { ALL_BACKENDS, ALL_LIBS, FEATURE_MAP, findUserConfig, readUserConfig };

package/src/fetcher/telemetry.ts

@@ -10,7 +10,7 @@ const DOWNLOAD_EVENT_ENDPOINT = 'https://ai.swmansion.com/telemetry/downloads/ap
 // self-referencing import would need package `exports` support in the consuming
 // bundler to load at all. A wrong value here is analytics noise; a failed
 // import would break the bundle.
-const LIB_VERSION = '0.10.0';
+const LIB_VERSION = '0.10.1';
 
 // Anonymous analytics are on by default; apps opt out via setTelemetryEnabled.
 let telemetryEnabled = true;