[build-tools] support Gradle build cache for Android builds (#3510)

AbbanMustafa · web-flow · commit c9cdfd1eb569 · 2026-03-26T12:34:18.000-05:00
* gradle cache

* cache modules-2

* cache modules-2

* proper path

* set properties, rename

* rem modules-2

* set org.gradle.cache.cleanup to ALWAYS

* set org.gradle.cache.cleanup to ALWAYS

* consolidate caches in restore/save step

* restore gradle

* cleanup nullthrows

* always set properties if env set, cleanup

* consistent path, clean log

* modify gradle props in trycatch

* eas-cache-cleanup script

* shorter prune
diff --git a/packages/build-tools/src/builders/android.ts b/packages/build-tools/src/builders/android.ts
@@ -14,8 +14,12 @@ import { eagerBundleAsync, shouldUseEagerBundle } from '../common/eagerBundle';
 import { prebuildAsync } from '../common/prebuild';
 import { setupAsync } from '../common/setup';
 import { Artifacts, BuildContext, SkipNativeBuildError } from '../context';
-import { cacheStatsAsync, restoreCcacheAsync } from '../steps/functions/restoreBuildCache';
-import { saveCcacheAsync } from '../steps/functions/saveBuildCache';
+import {
+  cacheStatsAsync,
+  restoreCcacheAsync,
+  restoreGradleCacheAsync,
+} from '../steps/functions/restoreBuildCache';
+import { saveCcacheAsync, saveGradleCacheAsync } from '../steps/functions/saveBuildCache';
 import {
   injectConfigureVersionGradleConfig,
   injectCredentialsGradleConfig,
@@ -81,6 +85,12 @@ async function buildAsync(ctx: BuildContext<Android.Job>): Promise<void> {
       env: ctx.env,
       secrets: ctx.job.secrets,
     });
+    await restoreGradleCacheAsync({
+      logger: ctx.logger,
+      workingDirectory,
+      env: ctx.env,
+      secrets: ctx.job.secrets,
+    });
   });
 
   await ctx.runBuildPhase(BuildPhase.POST_INSTALL_HOOK, async () => {
@@ -196,6 +206,12 @@ async function buildAsync(ctx: BuildContext<Android.Job>): Promise<void> {
       env: ctx.env,
       secrets: ctx.job.secrets,
     });
+    await saveGradleCacheAsync({
+      logger: ctx.logger,
+      workingDirectory,
+      env: ctx.env,
+      secrets: ctx.job.secrets,
+    });
   });
 
   await ctx.runBuildPhase(BuildPhase.CACHE_STATS, async () => {
diff --git a/packages/build-tools/src/steps/functions/restoreBuildCache.ts b/packages/build-tools/src/steps/functions/restoreBuildCache.ts
@@ -7,7 +7,10 @@ import {
   BuildStepInputValueTypeName,
   spawnAsync,
 } from '@expo/steps';
+import fs from 'fs';
 import nullthrows from 'nullthrows';
+import os from 'os';
+import path from 'path';
 
 import { sendCcacheStatsAsync } from './ccacheStats';
 import { decompressCacheAsync, downloadCacheAsync, downloadPublicCacheAsync } from './restoreCache';
@@ -16,6 +19,7 @@ import {
   generateDefaultBuildCacheKeyAsync,
   getCcachePath,
 } from '../../utils/cacheKey';
+import { GRADLE_CACHE_KEY_PREFIX, generateGradleCacheKeyAsync } from '../../utils/gradleCacheKey';
 import { TurtleFetchError } from '../../utils/turtleFetch';
 
 export function createRestoreBuildCacheFunction(): BuildFunction {
@@ -50,6 +54,15 @@ export function createRestoreBuildCacheFunction(): BuildFunction {
         env,
         secrets: stepCtx.global.staticContext.job.secrets,
       });
+
+      if (platform === Platform.ANDROID) {
+        await restoreGradleCacheAsync({
+          logger,
+          workingDirectory,
+          env,
+          secrets: stepCtx.global.staticContext.job.secrets,
+        });
+      }
     },
   });
 }
@@ -176,6 +189,106 @@ export async function restoreCcacheAsync({
   }
 }
 
+export async function restoreGradleCacheAsync({
+  logger,
+  workingDirectory,
+  env,
+  secrets,
+}: {
+  logger: bunyan;
+  workingDirectory: string;
+  env: Record<string, string | undefined>;
+  secrets?: { robotAccessToken?: string };
+}): Promise<void> {
+  if (env.EXPERIMENTAL_EAS_GRADLE_CACHE !== '1') {
+    return;
+  }
+
+  try {
+    const gradlePropertiesPath = path.join(workingDirectory, 'android', 'gradle.properties');
+    const gradlePropertiesContent = await fs.promises.readFile(gradlePropertiesPath, 'utf-8');
+    await fs.promises.writeFile(
+      gradlePropertiesPath,
+      `${gradlePropertiesContent}\n\norg.gradle.caching=true\n`
+    );
+
+    // Configure cache cleanup via init script (works with both Gradle 8 and 9,
+    // org.gradle.cache.cleanup property was removed in Gradle 9)
+    const initScriptDir = path.join(os.homedir(), '.gradle', 'init.d');
+    await fs.promises.mkdir(initScriptDir, { recursive: true });
+    await fs.promises.writeFile(
+      path.join(initScriptDir, 'eas-cache-cleanup.gradle'),
+      [
+        'def cacheDir = new File(System.getProperty("user.home"), ".gradle/caches/build-cache-1")',
+        'def countBefore = cacheDir.exists() ? cacheDir.listFiles()?.length ?: 0 : 0',
+        'println "[EAS] Gradle build cache entries before cleanup: ${countBefore}"',
+        '',
+        'beforeSettings { settings ->',
+        '    try {',
+        '        settings.caches {',
+        '            cleanup = Cleanup.ALWAYS',
+        '            buildCache {',
+        '                setRemoveUnusedEntriesAfterDays(3)',
+        '            }',
+        '        }',
+        '        println "[EAS] Configured Gradle cache cleanup via init script"',
+        '    } catch (Exception e) {',
+        '        println "[EAS] Failed to configure cache cleanup: ${e.message}"',
+        '    }',
+        '}',
+        '',
+        'gradle.buildFinished {',
+        '    def countAfter = cacheDir.exists() ? cacheDir.listFiles()?.length ?: 0 : 0',
+        '    println "[EAS] Gradle build cache entries after build: ${countAfter} (was ${countBefore})"',
+        '}',
+        '',
+      ].join('\n')
+    );
+
+    const robotAccessToken = nullthrows(
+      secrets?.robotAccessToken,
+      'Robot access token is required for cache operations'
+    );
+    const expoApiServerURL = nullthrows(env.__API_SERVER_URL, '__API_SERVER_URL is not set');
+    const jobId = nullthrows(env.EAS_BUILD_ID, 'EAS_BUILD_ID is not set');
+    const cacheKey = await generateGradleCacheKeyAsync(workingDirectory);
+    logger.info(`Restoring Gradle cache key: ${cacheKey}`);
+
+    const gradleCachesPath = path.join(os.homedir(), '.gradle', 'caches');
+
+    const buildCachePath = path.join(gradleCachesPath, 'build-cache-1');
+
+    const { archivePath, matchedKey } = await downloadCacheAsync({
+      logger,
+      jobId,
+      expoApiServerURL,
+      robotAccessToken,
+      paths: [buildCachePath],
+      key: cacheKey,
+      keyPrefixes: [GRADLE_CACHE_KEY_PREFIX],
+      platform: Platform.ANDROID,
+    });
+
+    await fs.promises.mkdir(gradleCachesPath, { recursive: true });
+    await decompressCacheAsync({
+      archivePath,
+      workingDirectory: gradleCachesPath,
+      verbose: env.EXPO_DEBUG === '1',
+      logger,
+    });
+
+    logger.info(
+      `Gradle cache restored to ${gradleCachesPath} ${matchedKey === cacheKey ? '(direct hit)' : '(prefix match)'}`
+    );
+  } catch (err: unknown) {
+    if (err instanceof TurtleFetchError && err.response?.status === 404) {
+      logger.info('No Gradle cache found for this key');
+    } else {
+      logger.warn('Failed to restore Gradle cache: ', err);
+    }
+  }
+}
+
 export async function cacheStatsAsync({
   logger,
   env,
diff --git a/packages/build-tools/src/steps/functions/saveBuildCache.ts b/packages/build-tools/src/steps/functions/saveBuildCache.ts
@@ -10,8 +10,13 @@ import {
 import fs from 'fs';
 import nullthrows from 'nullthrows';
 
+import os from 'os';
+import path from 'path';
+
 import { compressCacheAsync, uploadCacheAsync } from './saveCache';
+import { formatBytes } from '../../utils/artifacts';
 import { generateDefaultBuildCacheKeyAsync, getCcachePath } from '../../utils/cacheKey';
+import { generateGradleCacheKeyAsync } from '../../utils/gradleCacheKey';
 
 export function createSaveBuildCacheFunction(evictUsedBefore: Date): BuildFunction {
   return new BuildFunction({
@@ -46,6 +51,15 @@ export function createSaveBuildCacheFunction(evictUsedBefore: Date): BuildFuncti
         env,
         secrets: stepCtx.global.staticContext.job.secrets,
       });
+
+      if (platform === Platform.ANDROID) {
+        await saveGradleCacheAsync({
+          logger,
+          workingDirectory,
+          env,
+          secrets: stepCtx.global.staticContext.job.secrets,
+        });
+      }
     },
   });
 }
@@ -135,3 +149,66 @@ export async function saveCcacheAsync({
     logger.error({ err }, 'Failed to save cache');
   }
 }
+
+export async function saveGradleCacheAsync({
+  logger,
+  workingDirectory,
+  env,
+  secrets,
+}: {
+  logger: bunyan;
+  workingDirectory: string;
+  env: Record<string, string | undefined>;
+  secrets?: { robotAccessToken?: string };
+}): Promise<void> {
+  if (env.EXPERIMENTAL_EAS_GRADLE_CACHE !== '1') {
+    return;
+  }
+
+  const gradleCachesPath = path.join(os.homedir(), '.gradle', 'caches');
+  const buildCachePath = path.join(gradleCachesPath, 'build-cache-1');
+
+  try {
+    await fs.promises.access(buildCachePath);
+  } catch {
+    logger.warn('No Gradle build cache found, skipping save');
+    return;
+  }
+
+  try {
+    const cacheKey = await generateGradleCacheKeyAsync(workingDirectory);
+    logger.info(`Saving Gradle cache key: ${cacheKey}`);
+
+    const jobId = nullthrows(env.EAS_BUILD_ID, 'EAS_BUILD_ID is not set');
+    const robotAccessToken = nullthrows(
+      secrets?.robotAccessToken,
+      'Robot access token is required for cache operations'
+    );
+    const expoApiServerURL = nullthrows(env.__API_SERVER_URL, '__API_SERVER_URL is not set');
+
+    logger.info('Compressing Gradle build cache...');
+    const { archivePath } = await compressCacheAsync({
+      paths: [buildCachePath],
+      workingDirectory: gradleCachesPath,
+      verbose: env.EXPO_DEBUG === '1',
+      logger,
+    });
+
+    const { size } = await fs.promises.stat(archivePath);
+    logger.info(`Gradle cache archive size: ${formatBytes(size)}`);
+
+    await uploadCacheAsync({
+      logger,
+      jobId,
+      expoApiServerURL,
+      robotAccessToken,
+      archivePath,
+      key: cacheKey,
+      paths: [buildCachePath],
+      size,
+      platform: Platform.ANDROID,
+    });
+  } catch (err) {
+    logger.error({ err }, 'Failed to save Gradle cache');
+  }
+}
diff --git a/packages/build-tools/src/utils/gradleCacheKey.ts b/packages/build-tools/src/utils/gradleCacheKey.ts
@@ -0,0 +1,21 @@
+import * as PackageManagerUtils from '@expo/package-manager';
+import { hashFiles } from '@expo/steps';
+import path from 'path';
+
+import { findPackagerRootDir } from './packageManager';
+
+export const GRADLE_CACHE_KEY_PREFIX = 'android-gradle-cache-';
+
+export async function generateGradleCacheKeyAsync(workingDirectory: string): Promise<string> {
+  const packagerRunDir = findPackagerRootDir(workingDirectory);
+  const manager = PackageManagerUtils.createForProject(packagerRunDir);
+  const lockPath = path.join(packagerRunDir, manager.lockFile);
+
+  try {
+    return `${GRADLE_CACHE_KEY_PREFIX}${hashFiles([lockPath])}`;
+  } catch (err: unknown) {
+    throw new Error(
+      `Failed to read lockfile for Gradle cache key generation: ${err instanceof Error ? err.message : err}`
+    );
+  }
+}
