Add a simpler way to use a local Flutter engine (#225)

update_flutter_engine and build_flutter_assets now check for an
engine_override file at the root of the repository to trigger the
use of a local engine. Updates the README to link to instructions
on using it.

Since this adds more logic to build_flutter_assets, it has been
rewritten in Dart.

There are some obvious limitations (e.g., hard-coded name/location
requirement, copying every time instead of only when the
local build has changed), which can be addressed in the future if
there's sufficient demand. Since it is only intended for temporary use
when debugging, or testing engine changes, this may be sufficient,
and is a significant improvement over managing it manually.

Unlike .flutter_location_config this has no leading ., and is in the
repository rather than above it. This difference is intentional,
since unlike .flutter_location_config this is for temporary use,
so having it show up in directory listings and git status is
helpful as a reminder that it is enabled.

Fixes #160

Author: stuartmorgan

LocalEngine.md

@@ -0,0 +1,35 @@
+# Running a Locally Built Flutter Engine
+
+It may be useful for debugging or development to run with a [locally built
+Flutter engine](https://github.com/flutter/flutter/wiki/Compiling-the-engine).
+To temporarily override the normal behavior of `update_flutter_engine` and
+`build_flutter_assets`, add a file called `engine_override` at the root of
+your `flutter_desktop_embedding` checkout. For instance, on macOS or Linux:
+```
+$ echo host_debug_unopt > engine_override
+```
+
+This will cause `update_flutter_engine` to copy your local engine instead of
+downloading a prebuilt engine, and `build_flutter_assets` to pass the
+`--local-engine` flag when building assets.
+
+**Important**: Your Flutter engine checkout must be in a folder called `engine`
+(as recommended in the [setup
+instructions](https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment)),
+which must be next to your `flutter` checkout, or `update_flutter_engine` will
+fail.
+
+## Dart Changes
+
+If you change any Dart code in your engine, be sure to follow the instructions
+[here](https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment)
+or
+[here](https://github.com/flutter/flutter/wiki/The-flutter-tool#using-a-locally-built-engine-with-the-flutter-tool)
+for adding a `dependency_overrides` section to your `pubspec.yaml`.
+
+## Switching Back to a Prebuilt Engine
+
+To stop using your local engine, just delete `engine_override` (and
+`dependency_overrides` if you added them to `pubspec.yaml`) and rebuild.
+`update_flutter_engine` will automatically re-download the correct prebuilt
+engine.

README.md

@@ -60,6 +60,8 @@ with this library.
 Debugging of the Flutter side of a desktop application is possible, but requires
 [a modified workflow](Debugging.md).
 
+To debug the Flutter engine, you can [use a local engine build](LocalEngine.md).
+
 ## Feedback and Discussion
 
 For bug reports and specific feature requests, you can file GitHub issues. For

tools/build_flutter_assets

@@ -14,22 +14,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# This script runs the necessary Flutter commands to build the Flutter assets
-# than need to be packaged in an embedding application.
-# It should be called with one argument, which is the directory of the
-# Flutter application to build.
+# Runs build_flutter_assets.dart, using the output of flutter_location as
+# --flutter_root
 
 readonly base_dir="$(dirname "$0")"
-readonly flutter_dir="$("$base_dir/flutter_location")"
-readonly flutter_binary="$flutter_dir/bin/flutter"
-
-# To use a custom Flutter engine, uncomment the following variables, and set
-# engine_src_path to the path on your machine to your Flutter engine tree's
-# src/ directory (and build_type if your engine build is not debug).
-#readonly engine_src_path="/path/to/engine/src"
-#readonly build_type=host_debug_unopt
-#readonly extra_flags=(--local-engine-src-path $engine_src_path --local-engine=$build_type)
-
-cd "$1"
-echo Running "$flutter_binary" ${extra_flags[*]} build bundle
-exec "$flutter_binary" ${extra_flags[*]} build bundle
+readonly flutter_dir="$("${base_dir}/flutter_location")"
+exec "${base_dir}/run_dart_tool" build_flutter_assets \
+	--flutter_root="${flutter_dir}" "$@"

tools/build_flutter_assets.bat

@@ -11,24 +11,11 @@
 :: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 :: See the License for the specific language governing permissions and
 :: limitations under the License.
-@echo off
 
-:: This script runs the necessary Flutter commands to build the Flutter assets
-:: than need to be packaged in an embedding application.
-:: It should be called with one argument, which is the directory of the
-:: Flutter application to build.
-SETLOCAL ENABLEDELAYEDEXPANSION
+:: Runs build_flutter_assets.dart, using the output of flutter_location.bat as
+:: --flutter_root
+@echo off
 
 for /f "delims=" %%i in ('%~dp0flutter_location') do set FLUTTER_DIR=%%i
-set FLUTTER_BINARY=%FLUTTER_DIR%\bin\flutter
-
-:: To use a custom Flutter engine, uncomment the following variables, and set
-:: ENGINE_SRC_PATH to the path on your machine to your Flutter engine tree's
-:: src\ directory (and BUILD_TYPE if your engine build is not debug).
-::set ENGINE_SRC_PATH=path\to\engine\src
-::set BUILD_TYPE=host_debug_unopt
-::set EXTRA_FLAGS=--local-engine-src-path %ENGINE_SRC_PATH% --local-engine=%BUILD_TYPE%
 
-cd %1
-echo Running %FLUTTER_BINARY% %EXTRA_FLAGS% build bundle
-call %FLUTTER_BINARY% %EXTRA_FLAGS% build bundle
+call %~dp0.\run_dart_tool build_flutter_assets --flutter_root %FLUTTER_DIR% %*

tools/dart_tools/bin/build_flutter_assets.dart

@@ -0,0 +1,79 @@
+// Copyright 2019 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the 'License');
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an 'AS IS' BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// This script runs the necessary Flutter commands to build the Flutter assets
+// that need to be packaged in an embedding application.
+// It should be called with one argument, which is the directory of the
+// Flutter application to build.
+
+import 'dart:io';
+
+import 'package:args/args.dart';
+import 'package:path/path.dart' as path;
+
+import '../lib/flutter_utils.dart';
+import '../lib/run_command.dart';
+
+Future<void> main(List<String> arguments) async {
+  final parser = new ArgParser()
+    ..addOption('flutter_root',
+        help: 'The root of the Flutter tree to run \'flutter\' from.\n'
+            'Defaults to a "flutter" directory next to this repository.',
+        defaultsTo: getDefaultFlutterRoot())
+    ..addFlag('help', help: 'Prints this usage message.', negatable: false);
+  ArgResults parsedArguments;
+
+  try {
+    parsedArguments = parser.parse(arguments);
+  } on ArgParserException {
+    printUsage(parser);
+    exit(1);
+  }
+  if (parsedArguments.rest.length != 1) {
+    printUsage(parser);
+    exit(1);
+  }
+  final flutterApplicationDir = parsedArguments.rest[0];
+
+  final flutterName = Platform.isWindows ? 'flutter.bat' : 'flutter';
+  final flutterBinary =
+      path.join(parsedArguments['flutter_root'], 'bin', flutterName);
+  if (!File(flutterBinary).existsSync()) {
+    print("Error: No flutter binary at '$flutterBinary'");
+    exit(1);
+  }
+
+  final buildArguments = ['build', 'bundle'];
+
+  // Add --local-engine if an override is specified. --local-engine-src-path
+  // isn't provided since per
+  // https://github.com/flutter/flutter/wiki/The-flutter-tool
+  // it's not required if the engine directory is next to the flutter directory,
+  // which is currently the only configuration this project supports for local
+  // engines.
+  final engineOverride = await getEngineOverrideBuildType();
+  if (engineOverride != null) {
+    buildArguments.insertAll(0, ['--local-engine', engineOverride]);
+  }
+
+  await runCommand(flutterBinary, buildArguments,
+      workingDirectory: flutterApplicationDir);
+}
+
+/// Prints usage info for this utility.
+void printUsage(ArgParser argParser) {
+  print('Usage: build_flutter_assets [options] '
+      '<fluter application directory>\n');
+  print(argParser.usage);
+}

tools/dart_tools/bin/build_jsoncpp.dart

@@ -21,7 +21,7 @@ import 'dart:io';
 import 'package:args/args.dart';
 import 'package:path/path.dart' as path;
 
-import '../lib/runCommand.dart';
+import '../lib/run_command.dart';
 
 Future<void> main(List<String> arguments) async {
   if (!Platform.isWindows) {
@@ -62,7 +62,7 @@ Future<void> buildLibrary(String buildDirectory, {bool debug}) async {
     arguments.add('/p:Configuration=Release');
   }
   await runCommand('vcvars64.bat 1> nul &&', arguments,
-      workingDirectory: buildDirectory);
+      workingDirectory: buildDirectory, runInShell: true);
 }
 
 Future<void> copyLibraryToOutputDirectory(

tools/dart_tools/bin/fetch_jsoncpp.dart

@@ -17,7 +17,7 @@
 
 import 'dart:io';
 
-import '../lib/runCommand.dart';
+import '../lib/run_command.dart';
 
 // For the fork containing V2017 support. Once
 // https://github.com/open-source-parsers/jsoncpp/pull/853