[et] Allow users to update dependencies (#51177)

Allow users to update dependencies. Examples:

* `et fetch` Fetch dependencies

In the future, `et build` will update dependencies if it detects that they have changed.

Also:
* Updates the status in the README
* Adds instructions on how to run tests
* Fixes `et run`'s description
* Makes the `--verbose` flag global

Author: loic-sharma

testing/litetest/lib/src/matchers.dart

@@ -132,9 +132,9 @@ Matcher hasMatch(String pattern) => (dynamic d) {
       }
     };
 
-/// Gives a matcher that asserts that the value being matched is a List<String>
-/// that contains the entries in `pattern` in order. There may be values
-/// that are not in the pattern interleaved.
+/// Gives a matcher that asserts that the value being matched is a
+/// `List<String>` that contains the entries in `pattern` in order.
+/// There may be values that are not in the pattern interleaved.
 Matcher containsStringsInOrder(List<String> pattern) => (dynamic d) {
       expect(d, isInstanceOf<List<String>>());
       final List<String> input = d as List<String>;
@@ -148,6 +148,18 @@ Matcher containsStringsInOrder(List<String> pattern) => (dynamic d) {
         }
       }
       if (cursor < pattern.length) {
-        Expect.fail('Did not find ${pattern[cursor]} in $d}');
+        Expect.fail('Did not find ${pattern[cursor]} in $d');
+      }
+    };
+
+/// Gives a matcher that asserts that the value being matched is a
+/// `List<String>` that does not contain any of the values in `unexpected`.
+Matcher doesNotContainAny(List<String> unexpected) => (dynamic d) {
+      expect(d, isInstanceOf<List<String>>());
+      final List<String> input = d as List<String>;
+      for (final String string in input) {
+        if (unexpected.contains(string)) {
+          Expect.fail("String '$d' is unexpected");
+        }
       }
     };

tools/engine_tool/README.md

@@ -14,6 +14,8 @@ before it will work.
 The tool has the following commands.
 
 * `help` - Prints helpful information about commands and usage.
+* `build` - Builds the Flutter engine.
+* `fetch` - Downloads Flutter engine dependencies.
 * `format` - Formats files in the engine tree using various off-the-shelf
 formatters.
 * `run` - Runs a flutter application with a local build of the engine.
@@ -27,7 +29,7 @@ GitHub issue [here](https://github.com/flutter/flutter/issues/132807). Some
 desirable new features would do the following:
 
 * Add a `doctor` command.
-* Update the engine checkout so that engine developers no longer have to remeber
+* Update the engine checkout so that engine developers no longer have to remember
 to run `gclient sync -D`.
 * Build and test the engine using CI configurations locally, with the
 possibility to override or add new build options and targets.
@@ -61,3 +63,9 @@ implementation, then write a fake implementation.
 * *Begin with the end in mind* - Start working from what the interface provided
 by this tool *should* be, then modify underlying scripts and tools to provide
 APIs to support that.
+
+Run tests using `//flutter/testing/run_tests.py`:
+
+```shell
+testing/run_tests.py --type dart-host --dart-host-filter flutter/tools/engine_tool
+```

tools/engine_tool/lib/src/commands/build_command.dart

@@ -17,7 +17,6 @@ final class BuildCommand extends CommandBase {
   }) {
     builds = runnableBuilds(environment, configs);
     debugCheckBuilds(builds);
-    // Add options here that are common to all queries.
     argParser.addOption(
       configFlag,
       abbr: 'c',
@@ -53,6 +52,7 @@ final class BuildCommand extends CommandBase {
       return 1;
     }
 
+    // TODO(loic-sharma): Fetch dependencies if needed.
     return runBuild(environment, build);
   }
 }

tools/engine_tool/lib/src/commands/command_runner.dart

@@ -7,6 +7,8 @@ import 'package:engine_build_configs/engine_build_configs.dart';
 
 import '../environment.dart';
 import 'build_command.dart';
+import 'fetch_command.dart';
+import 'flags.dart';
 import 'format_command.dart';
 import 'query_command.dart';
 import 'run_command.dart';
@@ -22,14 +24,20 @@ final class ToolCommandRunner extends CommandRunner<int> {
     required this.configs,
   }) : super(toolName, toolDescription, usageLineLength: _usageLineLength) {
     final List<Command<int>> commands = <Command<int>>[
-      FormatCommand(
-        environment: environment,
-      ),
+      FetchCommand(environment: environment),
+      FormatCommand(environment: environment),
       QueryCommand(environment: environment, configs: configs),
       BuildCommand(environment: environment, configs: configs),
       RunCommand(environment: environment, configs: configs),
     ];
     commands.forEach(addCommand);
+
+    argParser.addFlag(
+      verboseFlag,
+      abbr: 'v',
+      help: 'Prints verbose output',
+      negatable: false,
+    );
   }
 
   /// The name of the tool as reported in the tool's usage and help

tools/engine_tool/lib/src/commands/fetch_command.dart

@@ -0,0 +1,30 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import '../dependencies.dart';
+import 'command.dart';
+import 'flags.dart';
+
+/// The root 'fetch' command.
+final class FetchCommand extends CommandBase {
+  /// Constructs the 'fetch' command.
+  FetchCommand({
+    required super.environment,
+  });
+
+  @override
+  String get name => 'fetch';
+
+  @override
+  String get description => "Download the Flutter engine's dependencies";
+
+  @override
+  List<String> get aliases => const <String>['sync'];
+
+  @override
+  Future<int> run() {
+    final bool verbose = globalResults![verboseFlag] as bool;
+    return fetchDependencies(environment, verbose: verbose);
+  }
+}

tools/engine_tool/lib/src/commands/format_command.dart

@@ -47,12 +47,6 @@ final class FormatCommand extends CommandBase {
         abbr: 'q',
         help: 'Silences all log messages except for errors and warnings',
         negatable: false,
-      )
-      ..addFlag(
-        verboseFlag,
-        abbr: 'v',
-        help: 'Prints verbose output',
-        negatable: false,
       );
   }
 
@@ -67,7 +61,7 @@ final class FormatCommand extends CommandBase {
     final bool all = argResults![allFlag]! as bool;
     final bool dryRun = argResults![dryRunFlag]! as bool;
     final bool quiet = argResults![quietFlag]! as bool;
-    final bool verbose = argResults![verboseFlag]! as bool;
+    final bool verbose = globalResults![verboseFlag] as bool;
     final String formatPath = p.join(
       environment.engine.flutterDir.path, 'ci', 'bin', 'format.dart',
     );

tools/engine_tool/lib/src/commands/query_command.dart

@@ -36,12 +36,6 @@ final class QueryCommand extends CommandBase {
             if (entry.value.canRunOn(environment.platform))
               entry.key: entry.value.path,
         },
-      )
-      ..addFlag(
-        verboseFlag,
-        abbr: 'v',
-        help: 'Respond to queries with extra information',
-        negatable: false,
       );
 
     addSubcommand(QueryBuildersCommand(
@@ -85,7 +79,7 @@ final class QueryBuildersCommand extends CommandBase {
     // current platform.
     final bool all = parent!.argResults![allFlag]! as bool;
     final String? builderName = parent!.argResults![builderFlag] as String?;
-    final bool verbose = parent!.argResults![verboseFlag] as bool;
+    final bool verbose = globalResults![verboseFlag]! as bool;
     if (!verbose) {
       environment.logger.status(
         'Add --verbose to see detailed information about each builder',

tools/engine_tool/lib/src/commands/run_command.dart

@@ -46,10 +46,10 @@ final class RunCommand extends CommandBase {
   String get name => 'run';
 
   @override
-  String get description => 'Run a flutter app with a local engine build'
+  String get description => 'Run a Flutter app with a local engine build. '
       'All arguments after -- are forwarded to flutter run, e.g.: '
-      'et run -- --profile'
-      'et run -- -d macos'
+      'et run -- --profile '
+      'et run -- -d macos '
       'See `flutter run --help` for a listing';
 
   Build? _lookup(String configName) {
@@ -123,7 +123,7 @@ final class RunCommand extends CommandBase {
   @override
   Future<int> run() async {
     if (!environment.processRunner.processManager.canRun('flutter')) {
-      environment.logger.error('Cannot find flutter command in your path');
+      environment.logger.error('Cannot find the flutter command in your path');
       return 1;
     }
     final String? configName = await _selectTargetConfig();

tools/engine_tool/lib/src/dependencies.dart

@@ -0,0 +1,57 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:io' as io;
+
+import 'package:process_runner/process_runner.dart';
+
+import 'environment.dart';
+import 'logger.dart';
+
+/// Update Flutter engine dependencies. Returns an exit code.
+Future<int> fetchDependencies(
+  Environment environment, {
+  bool verbose = false,
+}) async {
+  if (!environment.processRunner.processManager.canRun('gclient')) {
+    environment.logger.error('Cannot find the gclient command in your path');
+    return 1;
+  }
+
+  environment.logger.status('Fetching dependencies... ', newline: verbose);
+
+  Spinner? spinner;
+  ProcessRunnerResult result;
+  try {
+    if (!verbose) {
+      spinner = environment.logger.startSpinner();
+    }
+
+    result = await environment.processRunner.runProcess(
+      <String>[
+        'gclient',
+        'sync',
+        '-D',
+      ],
+      runInShell: true,
+      startMode: verbose
+        ? io.ProcessStartMode.inheritStdio
+        : io.ProcessStartMode.normal,
+    );
+  } finally {
+    spinner?.finish();
+  }
+
+  if (result.exitCode != 0) {
+    environment.logger.error('Fetching dependencies failed.');
+
+    // Verbose mode already logged output by making the child process inherit
+    // this process's stdio handles.
+    if (!verbose) {
+      environment.logger.error('Output:\n${result.output}');
+    }
+  }
+
+  return result.exitCode;
+}

tools/engine_tool/test/build_command_test.dart

@@ -134,9 +134,10 @@ void main() {
     ]);
     expect(result, equals(0));
     expect(runHistory.length, greaterThanOrEqualTo(3));
-    expect(runHistory[2].length, greaterThanOrEqualTo(2));
-    expect(runHistory[2][0], contains('python3'));
-    expect(runHistory[2][1], contains('gen/script.py'));
+    expect(
+      runHistory[2],
+      containsStringsInOrder(<String>['python3', 'gen/script.py']),
+    );
   });
 
   test('build command does not invoke tests', () async {

tools/engine_tool/test/fetch_command_test.dart

@@ -0,0 +1,83 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:ffi' as ffi show Abi;
+import 'dart:io' as io;
+
+import 'package:engine_build_configs/engine_build_configs.dart';
+import 'package:engine_repo_tools/engine_repo_tools.dart';
+import 'package:engine_tool/src/commands/command_runner.dart';
+import 'package:engine_tool/src/environment.dart';
+import 'package:engine_tool/src/logger.dart';
+import 'package:litetest/litetest.dart';
+import 'package:platform/platform.dart';
+import 'package:process_fakes/process_fakes.dart';
+import 'package:process_runner/process_runner.dart';
+
+void main() {
+  final Engine? engine = Engine.tryFindWithin();
+  if (engine == null) {
+    io.stderr.writeln('The current working directory is not a Flutter engine');
+    io.exitCode = 1;
+    return;
+  }
+
+  final Map<String, BuilderConfig> configs = <String, BuilderConfig>{};
+
+  (Environment, List<List<String>>) linuxEnv(Logger logger) {
+    final List<List<String>> runHistory = <List<String>>[];
+    return (
+      Environment(
+        abi: ffi.Abi.linuxX64,
+        engine: engine,
+        platform: FakePlatform(operatingSystem: Platform.linux),
+        processRunner: ProcessRunner(
+          processManager: FakeProcessManager(onStart: (List<String> command) {
+            runHistory.add(command);
+            return FakeProcess();
+          }, onRun: (List<String> command) {
+            runHistory.add(command);
+            return io.ProcessResult(81, 0, '', '');
+          }),
+        ),
+        logger: logger,
+      ),
+      runHistory
+    );
+  }
+
+  test('fetch command invokes gclient sync -D', () async {
+    final Logger logger = Logger.test();
+    final (Environment env, List<List<String>> runHistory) = linuxEnv(logger);
+    final ToolCommandRunner runner = ToolCommandRunner(
+      environment: env,
+      configs: configs,
+    );
+    final int result =
+        await runner.run(<String>['fetch']);
+    expect(result, equals(0));
+    expect(runHistory.length, greaterThanOrEqualTo(1));
+    expect(
+      runHistory[0],
+      containsStringsInOrder(<String>['gclient', 'sync', '-D']),
+    );
+  });
+
+  test('fetch command has sync alias', () async {
+    final Logger logger = Logger.test();
+    final (Environment env, List<List<String>> runHistory) = linuxEnv(logger);
+    final ToolCommandRunner runner = ToolCommandRunner(
+      environment: env,
+      configs: configs,
+    );
+    final int result =
+        await runner.run(<String>['sync']);
+    expect(result, equals(0));
+    expect(runHistory.length, greaterThanOrEqualTo(1));
+    expect(
+      runHistory[0],
+      containsStringsInOrder(<String>['gclient', 'sync', '-D']),
+    );
+  });
+}