ccache isn't used by iOS builds because CCACHE_BINARY is missing

[Nezz]

Description

Even if ccache is enabled for iOS builds, it's never actually used. The issue seems to originate from this PR:
#48257

The CCACHE_BINARY user-defined setting was added to Xcode, which the shell scripts will try to use as an env var. However, none of the user-defined settings become an env var, therefore ccache is never invoked (as of Xcode 26.2).

You can test the env vars by adding the following line to ccache-clang.sh:

env > ~/ccache.log

Steps to reproduce

1. Install ccache brew install ccache
2. Zero the ccache stats ccache -z
3. Check out the minimal repro project
4. Set up iOS dependencies cd ios && bundle install && bundle exec pod install
5. Build iOS using npm run ios or by opening the Xcode project

Expected outcome:
ccache is used and ccache -s contains stats

Actual outcome:
ccache is never called

React Native Version

0.83.1"

Affected Platforms

Runtime - iOS, Build - MacOS

Output of npx @react-native-community/cli info

info Fetching system and libraries information...
System:
 OS: macOS 26.2
 CPU: (14) arm64 Apple M4 Max
 Memory: 632.27 MB / 36.00 GB
 Shell:
 version: "5.9"
 path: /bin/zsh
Binaries:
 Node:
 version: 25.5.0
 path: /opt/homebrew/bin/node
 Yarn: Not Found
 npm:
 version: 11.8.0
 path: /opt/homebrew/bin/npm
 Watchman: Not Found
Managers:
 CocoaPods:
 version: 1.16.2
 path: /opt/homebrew/bin/pod
SDKs:
 iOS SDK:
 Platforms:
 - DriverKit 25.2
 - iOS 26.2
 - macOS 26.2
 - tvOS 26.2
 - visionOS 26.2
 - watchOS 26.2
 Android SDK: Not Found
IDEs:
 Android Studio: 2025.1 AI-251.26094.121.2513.14007798
 Xcode:
 version: 26.2/17C52
 path: /usr/bin/xcodebuild
Languages:
 Java:
 version: 17.0.17
 path: /usr/bin/javac
 Ruby:
 version: 4.0.1
 path: /opt/homebrew/opt/ruby/bin/ruby
npmPackages:
 "@react-native-community/cli":
 installed: 20.0.0
 wanted: 20.0.0
 react:
 installed: 19.2.0
 wanted: 19.2.0
 react-native:
 installed: 0.83.1
 wanted: 0.83.1
 react-native-macos: Not Found
npmGlobalPackages:
 "*react-native*": Not Found
Android:
 hermesEnabled: true
 newArchEnabled: true
iOS:
 hermesEnabled: true
 newArchEnabled: true

Stacktrace or Logs

The ccache stats don't show any information other than size because it has never been hit:
Local storage:
 Cache size (GiB): 0.3 / 5.0 ( 5.80%)


Expected stats:

Cacheable calls: 0 / 1 ( 0.00%)
 Hits: 0
 Direct: 0
 Preprocessed: 0
 Misses: 0
Uncacheable calls: 1 / 1 (100.0%)

MANDATORY Reproducer

https://github.com/Nezz/react-native-repro/tree/repro/Ccache

Screenshots and Videos

No response

[thanksyouall]

Thanks! I created a patch for this bug.

Fix::

 # Xcode doesn't export user-defined build settings as env vars,
 # so CCACHE_BINARY may be empty. Fall back to PATH lookup.
 if [ -z "$CCACHE_BINARY" ]; then
 CCACHE_BINARY=$(command -v ccache)
 fi

react-native+0.81.5.patch:

diff --git a/node_modules/react-native/scripts/xcode/ccache-clang++.sh b/node_modules/react-native/scripts/xcode/ccache-clang++.sh
index 54ff8ba..d868208 100755
--- a/node_modules/react-native/scripts/xcode/ccache-clang++.sh
+++ b/node_modules/react-native/scripts/xcode/ccache-clang++.sh
@@ -11,4 +11,10 @@ REACT_NATIVE_CCACHE_CONFIGPATH=$SCRIPT_DIR/ccache.conf
 # Provide our config file if none is already provided
 export CCACHE_CONFIGPATH="${CCACHE_CONFIGPATH:-$REACT_NATIVE_CCACHE_CONFIGPATH}"
 
+# Xcode doesn't export user-defined build settings as env vars,
+# so CCACHE_BINARY may be empty. Fall back to PATH lookup.
+if [ -z "$CCACHE_BINARY" ]; then
+ CCACHE_BINARY=$(command -v ccache)
+fi
+
 exec $CCACHE_BINARY clang++ "$@"
diff --git a/node_modules/react-native/scripts/xcode/ccache-clang.sh b/node_modules/react-native/scripts/xcode/ccache-clang.sh
index 9b1a355..5088eb5 100755
--- a/node_modules/react-native/scripts/xcode/ccache-clang.sh
+++ b/node_modules/react-native/scripts/xcode/ccache-clang.sh
@@ -11,4 +11,10 @@ REACT_NATIVE_CCACHE_CONFIGPATH=$SCRIPT_DIR/ccache.conf
 # Provide our config file if none is already provided
 export CCACHE_CONFIGPATH="${CCACHE_CONFIGPATH:-$REACT_NATIVE_CCACHE_CONFIGPATH}"
 
+# Xcode doesn't export user-defined build settings as env vars,
+# so CCACHE_BINARY may be empty. Fall back to PATH lookup.
+if [ -z "$CCACHE_BINARY" ]; then
+ CCACHE_BINARY=$(command -v ccache)
+fi
+
 exec $CCACHE_BINARY clang "$@"

[marcospgp]

Confirming this on Xcode 26.5 (Apple clang 21) with React Native 0.85.3, reached through Expo SDK 56's expo-build-properties ios.ccacheEnabled: true (which sets :ccache_enabled => true).

Everything looks correctly wired: apple.ccacheEnabled is in Podfile.properties.json, the Pods project sets CC/CXX/LD/LDPLUSPLUS to the ccache-clang wrappers across all build configs, and CCACHE_BINARY is set as a build setting. Yet a full clean build records 0 cacheable calls and the cache stays empty.

I confirmed the root cause by replaying a verbatim CompileC command with CCACHE_DEBUG=1: Xcode 16+ exports user-defined build settings into shell-script phase environments but not into the CompileC task environment. So inside the wrapper CCACHE_BINARY is empty and exec $CCACHE_BINARY clang "$@" runs plain clang. The wrapper is invoked for every compile (553+ times in my build), but ccache is never actually reached. No CompileC block in the build log carries export CCACHE_BINARY, while shell-script phases do.

The command -v ccache fallback posted above fixes it. The CompileC task PATH does include Homebrew (both /opt/homebrew/bin and /usr/local/bin on a default install), so the lookup succeeds.

Measured impact after patching both wrappers, two clean xcodebuild runs with DerivedData wiped between them so the only difference is ccache state:

• cold (empty cache): 485s, 1586 cacheable calls, 0 hits / 1586 misses
• warm (populated): 126s, 1586 hits / 0 misses (100% hit rate)

So 3.85x faster on the warm clean rebuild, versus literally no caching before the patch.

Suggested wrapper change for both ccache-clang.sh and ccache-clang++.sh, preserving graceful degradation when ccache is absent (empty stays empty, so it falls back to plain clang and the build is unaffected):

if [ -z "$CCACHE_BINARY" ]; then
 CCACHE_BINARY="$(command -v ccache)"
fi
exec $CCACHE_BINARY clang "$@"