Start using bin/cache/engine.{stamp|realm} instead of bin/internal/engine.{realm|version}. (#164352)

matanlurey · web-flow · commit 71d50a16163b · 2025-03-02T00:54:33.000Z
Towards flutter/flutter#164315. See also: https://github.com/flutter/flutter/blob/master/docs/tool/Engine-artifacts.md. There are more usages in `flutter/flutter`, but some will require more specialized review (i.e. from release folks, or the Dart SDK team), so I'll split those off. ~~Requires flutter/flutter#164317 to merge first.~~ ✅
diff --git a/dev/bots/suite_runners/run_test_harness_tests.dart b/dev/bots/suite_runners/run_test_harness_tests.dart
@@ -133,8 +133,7 @@ Future<void> testHarnessTestsRunner() async {
   }
 }
 
-/// Verify the Flutter Engine is the revision in
-/// bin/cache/internal/engine.version.
+/// Verify the Flutter Engine is the revision in `bin/cache/engine.stamp`.
 Future<void> _validateEngineHash() async {
   final String flutterTester = path.join(
     flutterRoot,
@@ -146,6 +145,7 @@ Future<void> _validateEngineHash() async {
     'flutter_tester$exe',
   );
 
+  // TODO(matanlurey): Revisit with the Dart team if this is true now that they use FLUTTER_PREBUILT_ENGINE_VERSION=...
   if (runningInDartHHHBot) {
     // The Dart HHH bots intentionally modify the local artifact cache
     // and then use this script to run Flutter's test suites.
diff --git a/dev/bots/suite_runners/run_web_tests.dart b/dev/bots/suite_runners/run_web_tests.dart
@@ -91,8 +91,8 @@ class WebTestsSuite {
 
   /// Coarse-grained integration tests running on the Web.
   Future<void> webLongRunningTestsRunner() async {
-    final String engineVersionFile = path.join(flutterRoot, 'bin', 'internal', 'engine.version');
-    final String engineRealmFile = path.join(flutterRoot, 'bin', 'internal', 'engine.realm');
+    final String engineVersionFile = path.join(flutterRoot, 'bin', 'cache', 'engine.stamp');
+    final String engineRealmFile = path.join(flutterRoot, 'bin', 'cache', 'engine.realm');
     final String engineVersion = File(engineVersionFile).readAsStringSync().trim();
     final String engineRealm = File(engineRealmFile).readAsStringSync().trim();
     if (engineRealm.isNotEmpty) {
diff --git a/dev/bots/utils.dart b/dev/bots/utils.dart
@@ -61,7 +61,7 @@ final String flutterRoot = path.dirname(path.dirname(path.dirname(path.fromUri(P
 final String flutter = path.join(flutterRoot, 'bin', 'flutter$bat');
 final String dart = path.join(flutterRoot, 'bin', 'cache', 'dart-sdk', 'bin', 'dart$exe');
 final String pubCache = path.join(flutterRoot, '.pub-cache');
-final String engineVersionFile = path.join(flutterRoot, 'bin', 'internal', 'engine.version');
+final String engineVersionFile = path.join(flutterRoot, 'bin', 'cache', 'engine.stamp');
 final String luciBotId = Platform.environment['SWARMING_BOT_ID'] ?? '';
 final bool runningInDartHHHBot =
     luciBotId.startsWith('luci-dart-') || luciBotId.startsWith('dart-tests-');
diff --git a/dev/devicelab/bin/tasks/engine_dependency_proxy_test.dart b/dev/devicelab/bin/tasks/engine_dependency_proxy_test.dart
@@ -59,7 +59,7 @@ tasks.register("printEngineMavenUrl") {
 
         String realm =
             File(
-              path.join(flutterDirectory.path, 'bin', 'internal', 'engine.realm'),
+              path.join(flutterDirectory.path, 'bin', 'cache', 'engine.realm'),
             ).readAsStringSync().trim();
         if (realm.isNotEmpty) {
           realm = '$realm/';
diff --git a/dev/tools/create_api_docs.dart b/dev/tools/create_api_docs.dart
@@ -1265,7 +1265,7 @@ class FlutterInformation {
     info['engineRevision'] = flutterVersion['engineRevision'] as String;
     final File engineRealm = flutterRoot
         .childDirectory('bin')
-        .childDirectory('internal')
+        .childDirectory('cache')
         .childFile('engine.realm');
     info['engineRealm'] = engineRealm.existsSync() ? engineRealm.readAsStringSync().trim() : '';
 
diff --git a/dev/tools/find_engine_commit.dart b/dev/tools/find_engine_commit.dart
@@ -6,7 +6,7 @@ import 'dart:io';
 
 void _validate(List<String> args) {
   bool errors = false;
-  if (!File('bin/internal/engine.version').existsSync()) {
+  if (!File('bin/cache/engine.stamp').existsSync()) {
     errors = true;
     print('This program must be run from the root of your flutter repository.');
   }
diff --git a/dev/tools/test/create_api_docs_test.dart b/dev/tools/test/create_api_docs_test.dart
@@ -197,7 +197,7 @@ void main() {
           .childDirectory('user')
           .childDirectory('flutter')
           .childDirectory('bin')
-          .childDirectory('internal');
+          .childDirectory('cache');
       flutterHome.childFile('engine.realm')
         ..createSync(recursive: true)
         ..writeAsStringSync('realm');
diff --git a/packages/flutter_tools/gradle/aar_init_script.gradle b/packages/flutter_tools/gradle/aar_init_script.gradle
@@ -44,7 +44,7 @@ void configureProject(Project project, String outputDir) {
 
     String storageUrl = System.getenv('FLUTTER_STORAGE_BASE_URL') ?: "https://storage.googleapis.com"
 
-    String engineRealm = Paths.get(getFlutterRoot(project), "bin", "internal", "engine.realm")
+    String engineRealm = Paths.get(getFlutterRoot(project), "bin", "cache", "engine.realm")
         .toFile().text.trim()
     if (engineRealm) {
         engineRealm += "/"
@@ -57,7 +57,7 @@ void configureProject(Project project, String outputDir) {
             url "$storageUrl/${engineRealm}download.flutter.io"
         }
     }
-    String engineVersion = Paths.get(getFlutterRoot(project), "bin", "internal", "engine.version")
+    String engineVersion = Paths.get(getFlutterRoot(project), "bin", "cache", "engine.stamp")
         .toFile().text.trim()
     project.dependencies {
         // Add the embedding dependency.
@@ -179,7 +179,7 @@ projectsEvaluated {
             // Configure the `assembleAar<variantName>` task for each plugin's projects and make
             // the module's equivalent task depend on the plugin's task.
             String variantName = variant.name.capitalize()
-            
+
                 Task moduleProjectTask = moduleProject.tasks.named("assembleAar$variantName").get()
                 assert(moduleProjectTask != null)
                 Task pluginProjectTask = pluginProject.tasks.named("assembleAar$variantName").get()
diff --git a/packages/flutter_tools/gradle/resolve_dependencies.gradle.kts b/packages/flutter_tools/gradle/resolve_dependencies.gradle.kts
@@ -25,8 +25,8 @@ val engineVersion =
     Paths.get(
         flutterRoot.absolutePath,
         "bin",
-        "internal",
-        "engine.version"
+        "cache",
+        "engine.stamp"
     )
         .toFile()
         .readText()
@@ -36,7 +36,7 @@ var engineRealm =
     Paths.get(
         flutterRoot.absolutePath,
         "bin",
-        "internal",
+        "cache",
         "engine.realm"
     )
         .toFile()
diff --git a/packages/flutter_tools/gradle/src/main/groovy/flutter.groovy b/packages/flutter_tools/gradle/src/main/groovy/flutter.groovy
@@ -213,9 +213,9 @@ class FlutterPlugin implements Plugin<Project> {
 
         engineVersion = useLocalEngine()
             ? "+" // Match any version since there's only one.
-            : "1.0.0-" + Paths.get(flutterRoot.absolutePath, "bin", "internal", "engine.version").toFile().text.trim()
+            : "1.0.0-" + Paths.get(flutterRoot.absolutePath, "bin", "cache", "engine.stamp").toFile().text.trim()
 
-        engineRealm = Paths.get(flutterRoot.absolutePath, "bin", "internal", "engine.realm").toFile().text.trim()
+        engineRealm = Paths.get(flutterRoot.absolutePath, "bin", "cache", "engine.realm").toFile().text.trim()
         if (engineRealm) {
             engineRealm += "/"
         }
diff --git a/packages/flutter_tools/lib/src/build_system/source.dart b/packages/flutter_tools/lib/src/build_system/source.dart
@@ -165,16 +165,16 @@ class SourceVisitor implements ResolvedFiles {
   ///
   /// If the [Artifact] points to a directory then all child files are included.
   /// To increase the performance of builds that use a known revision of Flutter,
-  /// these are updated to point towards the engine.version file instead of
+  /// these are updated to point towards the `engine.stamp` file instead of
   /// the artifact itself.
   void visitArtifact(Artifact artifact, TargetPlatform? platform, BuildMode? mode) {
     // This is not a local engine.
     if (environment.engineVersion != null) {
       sources.add(
         environment.flutterRootDir
             .childDirectory('bin')
-            .childDirectory('internal')
-            .childFile('engine.version'),
+            .childDirectory('cache')
+            .childFile('engine.stamp'),
       );
       return;
     }
@@ -199,16 +199,16 @@ class SourceVisitor implements ResolvedFiles {
   ///
   /// If the [Artifact] points to a directory then all child files are included.
   /// To increase the performance of builds that use a known revision of Flutter,
-  /// these are updated to point towards the engine.version file instead of
+  /// these are updated to point towards the `engine.stamp` file instead of
   /// the artifact itself.
   void visitHostArtifact(HostArtifact artifact) {
     // This is not a local engine.
     if (environment.engineVersion != null) {
       sources.add(
         environment.flutterRootDir
             .childDirectory('bin')
-            .childDirectory('internal')
-            .childFile('engine.version'),
+            .childDirectory('cache')
+            .childFile('engine.stamp'),
       );
       return;
     }
diff --git a/packages/flutter_tools/lib/src/cache.dart b/packages/flutter_tools/lib/src/cache.dart
@@ -491,7 +491,7 @@ class Cache {
 
   /// The current version of the Flutter engine the flutter tool will download.
   String get engineRevision {
-    _engineRevision ??= getVersionFor('engine');
+    _engineRevision ??= getStampFor('engine');
     if (_engineRevision == null) {
       throwToolExit('Could not determine engine revision.');
     }
@@ -684,12 +684,14 @@ class Cache {
     return versionFile.existsSync() ? versionFile.readAsStringSync().trim() : null;
   }
 
+  // TODO(matanlurey): Remove the ability to do "generic" realms, and special case for engine.
+  // https://github.com/flutter/flutter/issues/164315
   String? getRealmFor(String artifactName) {
     final File realmFile = _fileSystem.file(
       _fileSystem.path.join(
         _rootOverride?.path ?? flutterRoot!,
         'bin',
-        'internal',
+        'cache',
         '$artifactName.realm',
       ),
     );
@@ -930,6 +932,9 @@ abstract class EngineCachedArtifact extends CachedArtifact {
   @override
   final String stampName;
 
+  @override
+  String? get version => cache.engineRevision;
+
   /// Return a list of (directory path, download URL path) tuples.
   List<List<String>> getBinaryDirs();
 
diff --git a/packages/flutter_tools/lib/src/flutter_cache.dart b/packages/flutter_tools/lib/src/flutter_cache.dart
@@ -171,7 +171,7 @@ class FlutterWebSdk extends CachedArtifact {
   Directory get location => cache.getWebSdkDirectory();
 
   @override
-  String? get version => cache.getVersionFor('engine');
+  String? get version => cache.engineRevision;
 
   @override
   Future<void> updateInner(
@@ -568,7 +568,7 @@ class FlutterRunnerSDKArtifacts extends CachedArtifact {
   Directory get location => cache.getArtifactDirectory('flutter_runner');
 
   @override
-  String? get version => cache.getVersionFor('engine');
+  String? get version => cache.engineRevision;
 
   @override
   Future<void> updateInner(
@@ -627,7 +627,7 @@ class FlutterRunnerDebugSymbols extends CachedArtifact {
   Directory get location => cache.getArtifactDirectory(name);
 
   @override
-  String? get version => cache.getVersionFor('engine');
+  String? get version => cache.engineRevision;
 
   Future<void> _downloadDebugSymbols(String targetArch, ArtifactUpdater artifactUpdater) async {
     final String packageName = 'fuchsia-debug-symbols-$targetArch';
diff --git a/packages/flutter_tools/test/commands.shard/hermetic/build_darwin_framework_test.dart b/packages/flutter_tools/test/commands.shard/hermetic/build_darwin_framework_test.dart
@@ -54,7 +54,7 @@ void main() {
           fileSystem: memoryFileSystem,
           processManager: FakeProcessManager.any(),
         );
-        rootOverride.childDirectory('bin').childDirectory('internal').childFile('engine.version')
+        rootOverride.childDirectory('bin').childDirectory('cache').childFile('engine.stamp')
           ..createSync(recursive: true)
           ..writeAsStringSync(engineRevision);
       });
@@ -346,7 +346,7 @@ void main() {
           fileSystem: memoryFileSystem,
           processManager: FakeProcessManager.any(),
         );
-        rootOverride.childDirectory('bin').childDirectory('internal').childFile('engine.version')
+        rootOverride.childDirectory('bin').childDirectory('cache').childFile('engine.stamp')
           ..createSync(recursive: true)
           ..writeAsStringSync(engineRevision);
       });
diff --git a/packages/flutter_tools/test/general.shard/build_system/source_test.dart b/packages/flutter_tools/test/general.shard/build_system/source_test.dart
@@ -260,7 +260,7 @@ void main() {
   );
 
   test(
-    'Non-local engine builds use the engine.version file as an Artifact dependency',
+    'Non-local engine builds use the engine.stamp file as an Artifact dependency',
     () => testbed.run(() {
       final Artifacts artifacts = Artifacts.test();
       final Environment environment = Environment.test(
@@ -279,7 +279,7 @@ void main() {
       );
       fizzSource.accept(visitor);
 
-      expect(visitor.sources.single.path, contains('engine.version'));
+      expect(visitor.sources.single.path, contains('engine.stamp'));
     }),
   );
 }
diff --git a/packages/flutter_tools/test/general.shard/cache_test.dart b/packages/flutter_tools/test/general.shard/cache_test.dart
@@ -356,14 +356,14 @@ void main() {
 
     testWithoutContext('a non-empty realm is included in the storage url', () async {
       final MemoryFileSystem fileSystem = MemoryFileSystem.test();
-      final Directory internalDir = fileSystem.currentDirectory
+      final Directory cacheDir = fileSystem.currentDirectory
           .childDirectory('bin')
-          .childDirectory('internal');
-      final File engineVersionFile = internalDir.childFile('engine.version');
+          .childDirectory('cache');
+      final File engineVersionFile = cacheDir.childFile('engine.stamp');
       engineVersionFile.createSync(recursive: true);
       engineVersionFile.writeAsStringSync('abcdef');
 
-      final File engineRealmFile = internalDir.childFile('engine.realm');
+      final File engineRealmFile = cacheDir.childFile('engine.realm');
       engineRealmFile.createSync(recursive: true);
       engineRealmFile.writeAsStringSync('flutter_archives_v2');
 
@@ -465,7 +465,7 @@ void main() {
     expect(packageUrl, isNotNull);
     expect(
       packageUrl.toString(),
-      'https://storage.googleapis.com/flutter_infra_release/flutter/null/package_dir.zip',
+      'https://storage.googleapis.com/flutter_infra_release/flutter/abc123/package_dir.zip',
     );
 
     final Directory dir =
@@ -903,7 +903,10 @@ void main() {
       canvasKitVersionFile.createSync(recursive: true);
       canvasKitVersionFile.writeAsStringSync('abcdefg');
 
-      final File engineVersionFile = internalDir.childFile('engine.version');
+      final Directory cacheDir = fileSystem.currentDirectory
+          .childDirectory('bin')
+          .childDirectory('cache');
+      final File engineVersionFile = cacheDir.childFile('engine.stamp');
       engineVersionFile.createSync(recursive: true);
       engineVersionFile.writeAsStringSync('hijklmnop');
 
@@ -953,7 +956,10 @@ void main() {
       canvasKitVersionFile.createSync(recursive: true);
       canvasKitVersionFile.writeAsStringSync('abcdefg');
 
-      final File engineVersionFile = internalDir.childFile('engine.version');
+      final Directory cacheDir = fileSystem.currentDirectory
+          .childDirectory('bin')
+          .childDirectory('cache');
+      final File engineVersionFile = cacheDir.childFile('engine.stamp');
       engineVersionFile.createSync(recursive: true);
       engineVersionFile.writeAsStringSync('hijklmnop');
 
@@ -999,6 +1005,13 @@ void main() {
     final FakeArtifactUpdater artifactUpdater = FakeArtifactUpdater();
     final FlutterWebSdk webSdk = FlutterWebSdk(cache);
 
+    final Directory cacheDir = fileSystem.currentDirectory
+        .childDirectory('bin')
+        .childDirectory('cache');
+    final File engineVersionFile = cacheDir.childFile('engine.stamp');
+    engineVersionFile.createSync(recursive: true);
+    engineVersionFile.writeAsStringSync('hijklmnop');
+
     artifactUpdater.onDownloadZipArchive = (String message, Uri uri, Directory location) {
       location.createSync(recursive: true);
       location.childFile('foo').createSync();
@@ -1347,6 +1360,9 @@ class FakeSecondaryCache extends Fake implements Cache {
   @override
   String get storageBaseUrl => 'https://storage.googleapis.com';
 
+  @override
+  String get engineRevision => version ?? 'abc123';
+
   @override
   Directory getDownloadDir() => artifactDirectory;
 

Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@ import 'dart:io';`
`6`	`6`
`7`	`7`	`void _validate(List<String> args) {`
`8`	`8`	`bool errors = false;`
`9`		`- if (!File('bin/internal/engine.version').existsSync()) {`
	`9`	`+ if (!File('bin/cache/engine.stamp').existsSync()) {`
`10`	`10`	`errors = true;`
`11`	`11`	`print('This program must be run from the root of your flutter repository.');`
`12`	`12`	`}`