Update `flutter_tools/bin/*.(dart|sh)` to provide, if set, --local-engine-host. (#132336)

Partial work towards https://github.com/flutter/flutter/issues/132245.

Other than updating error messages, and passing `$LOCAL_ENGINE_HOST`
downwards, this PR should not change the behavior of any existing
workflows or code (i.e. it's purely additive).

packages/flutter_tools/bin/macos_assemble.sh

@@ -66,9 +66,23 @@ BuildApp() {
       EchoError "This engine is not compatible with FLUTTER_BUILD_MODE: '${build_mode}'."
       EchoError "You can fix this by updating the LOCAL_ENGINE environment variable, or"
       EchoError "by running:"
-      EchoError "  flutter build macos --local-engine=host_${build_mode}"
+      EchoError "  flutter build macos --local-engine=host_${build_mode} --local-engine-host=host_${build_mode}"
       EchoError "or"
-      EchoError "  flutter build macos --local-engine=host_${build_mode}_unopt"
+      EchoError "  flutter build macos --local-engine=host_${build_mode}_unopt --local-engine-host=host_${build_mode}_unopt"
+      EchoError "========================================================================"
+      exit -1
+    fi
+  fi
+  if [[ -n "$LOCAL_ENGINE_HOST" ]]; then
+    if [[ $(echo "$LOCAL_ENGINE_HOST" | tr "[:upper:]" "[:lower:]") != *"$build_mode"* ]]; then
+      EchoError "========================================================================"
+      EchoError "ERROR: Requested build with Flutter local engine at '${LOCAL_ENGINE_HOST}'"
+      EchoError "This engine is not compatible with FLUTTER_BUILD_MODE: '${build_mode}'."
+      EchoError "You can fix this by updating the LOCAL_ENGINE_HOST environment variable, or"
+      EchoError "by running:"
+      EchoError "  flutter build macos --local-engine=host_${build_mode} --local-engine-host=host_${build_mode}"
+      EchoError "or"
+      EchoError "  flutter build macos --local-engine=host_${build_mode}_unopt --local-engine-host=host_${build_mode}_unopt"
       EchoError "========================================================================"
       exit -1
     fi
@@ -94,6 +108,9 @@ BuildApp() {
   if [[ -n "$LOCAL_ENGINE" ]]; then
     flutter_args+=("--local-engine=${LOCAL_ENGINE}")
   fi
+  if [[ -n "$LOCAL_ENGINE_HOST" ]]; then
+    flutter_args+=("--local-engine-host=${LOCAL_ENGINE_HOST}")
+  fi
   flutter_args+=(
     "assemble"
     "--no-version-check"

packages/flutter_tools/bin/tool_backend.dart

@@ -21,6 +21,7 @@ Future<void> main(List<String> arguments) async {
     ?? pathJoin(<String>['lib', 'main.dart']);
   final String? codeSizeDirectory = Platform.environment['CODE_SIZE_DIRECTORY'];
   final String? localEngine = Platform.environment['LOCAL_ENGINE'];
+  final String? localEngineHost = Platform.environment['LOCAL_ENGINE_HOST'];
   final String? projectDirectory = Platform.environment['PROJECT_DIR'];
   final String? splitDebugInfo = Platform.environment['SPLIT_DEBUG_INFO'];
   final String? bundleSkSLPath = Platform.environment['BUNDLE_SKSL_PATH'];
@@ -46,9 +47,22 @@ ERROR: Requested build with Flutter local engine at '$localEngine'
 This engine is not compatible with FLUTTER_BUILD_MODE: '$buildMode'.
 You can fix this by updating the LOCAL_ENGINE environment variable, or
 by running:
-  flutter build <platform> --local-engine=host_$buildMode
+  flutter build <platform> --local-engine=<platform>_$buildMode --local-engine-host=host_$buildMode
 or
-  flutter build <platform> --local-engine=host_${buildMode}_unopt
+  flutter build <platform> --local-engine=<platform>_${buildMode}_unopt --local-engine-host=host_${buildMode}_unopt
+========================================================================
+''');
+    exit(1);
+  }
+  if (localEngineHost != null && !localEngineHost.contains(buildMode)) {
+    stderr.write('''
+ERROR: Requested build with Flutter local engine host at '$localEngineHost'
+This engine is not compatible with FLUTTER_BUILD_MODE: '$buildMode'.
+You can fix this by updating the LOCAL_ENGINE_HOST environment variable, or
+by running:
+  flutter build <platform> --local-engine=<platform>_$buildMode --local-engine-host=host_$buildMode
+or
+  flutter build <platform> --local-engine=<platform>_$buildMode --local-engine-host=host_${buildMode}_unopt
 ========================================================================
 ''');
     exit(1);
@@ -72,6 +86,7 @@ or
         '--prefixed-errors',
       if (flutterEngine != null) '--local-engine-src-path=$flutterEngine',
       if (localEngine != null) '--local-engine=$localEngine',
+      if (localEngineHost != null) '--local-engine-host=$localEngineHost',
       'assemble',
       '--no-version-check',
       '--output=build',

packages/flutter_tools/bin/xcode_backend.dart

@@ -345,6 +345,10 @@ class Context {
       flutterArgs.add('--local-engine=${environment['LOCAL_ENGINE']}');
     }
 
+    if (environment['LOCAL_ENGINE_HOST'] != null && environment['LOCAL_ENGINE_HOST']!.isNotEmpty) {
+      flutterArgs.add('--local-engine-host=${environment['LOCAL_ENGINE_HOST']}');
+    }
+
     flutterArgs.addAll(<String>[
       'assemble',
       '--no-version-check',

packages/flutter_tools/test/integration.shard/tool_backend_test.dart

@@ -70,4 +70,25 @@ void main() {
       ),
     );
   });
+
+  testWithoutContext('tool_backend.dart exits if local engine host does not match build mode', () async {
+    final ProcessResult result = await processManager.run(<String>[
+      dart,
+      toolBackend,
+      'linux-x64',
+      'debug',
+    ], environment: <String, String>{
+      'PROJECT_DIR': examplePath,
+      'LOCAL_ENGINE': 'debug_foo_bar', // OK
+      'LOCAL_ENGINE_HOST': 'release_foo_bar', // Does not contain "debug",
+    });
+
+    expect(
+      result,
+      const ProcessResultMatcher(
+        exitCode: 1,
+        stderrPattern: "ERROR: Requested build with Flutter local engine host at 'release_foo_bar'",
+      ),
+    );
+  });
 }