Merge pull request from google/master

.appveyor.yml

@@ -17,7 +17,10 @@ image: Visual Studio 2017
 platform: x64
 
 install:
-  - ps: build\ci\install_flutter.ps1 $env:APPVEYOR_BUILD_FOLDER\..
+  # None of the packaged channels are new enough for the current state
+  # of FDE, so for now clone master instead.
+  #- ps: build\ci\install_flutter.ps1 $env:APPVEYOR_BUILD_FOLDER\..
+  - git clone -b master https://github.com/flutter/flutter.git %APPVEYOR_BUILD_FOLDER%\..\flutter
 
 build_script:
-  - msbuild "example\windows\Example Embedder.sln"
+  - msbuild "example\windows_fde\Example Embedder.sln"

.travis.yml

@@ -25,7 +25,7 @@ matrix:
       before_script:
         - export PATH=$PATH:$TRAVIS_BUILD_DIR/../flutter/bin:$TRAVIS_BUILD_DIR/bin
       script:
-        - make -C example/linux
+        - make -C example/linux_fde
 
     - os: linux
       dist: xenial
@@ -39,11 +39,11 @@ matrix:
       before_script:
         - export PATH=$PATH:$TRAVIS_BUILD_DIR/bin
       script:
-        - make -C example/linux USE_GN=1
+        - make -C example/linux_fde USE_GN=1
 
     - os: osx
       language: objective-c
-      xcode_project: example/macos/ExampleEmbedder.xcodeproj
+      xcode_project: example/macos_fde/ExampleEmbedder.xcodeproj
       xcode_scheme: ExampleEmbedder
       install:
         - build/ci/install_flutter $TRAVIS_BUILD_DIR/..

Debugging.md

@@ -41,7 +41,7 @@ There are two options:
 The `flutter attach` command can connect to a desktop Flutter application
 and provide the same interactive command line that `flutter run` would provide.
 In the directory of the Flutter portion of your application (e.g.,
-`/example/flutter_app`) run:
+`/example/` for this project's example application) run:
 
 ```
 $ flutter attach --device-id=flutter-tester --debug-port=49494
@@ -52,7 +52,7 @@ necessary to bypass checks for an attached iOS or Android device.
 
 ### VS Code
 
-Open the Flutter portion of your application (e.g., `/example/flutter_app`).
+Open the Flutter portion of your application (e.g., `/example/`).
 Add a [launch
 configuration](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations)
 like the following, substituting your Observatory port:

Flutter-Requirements.md

@@ -62,3 +62,13 @@ on all platforms.
 
 Symptoms of missing fonts can include text failing to display, console logging
 about failure to load fonts, or in some cases crashes.
+
+## Plugins
+
+If your project uses any plugins with platform components, they won't
+work, as the native side will be missing. Depending on how the Dart side of the
+plugin is written, they may fail gracefully, or may throw errors.
+
+You may need to make the calls to those plugins conditional based on the host
+platform. Alternately, if you have the expertise, you could implement the native
+side of the plugin in your desktop project(s).

Quick-Start.md

@@ -0,0 +1,48 @@
+# Quick Start
+
+A common question for people discovering this project is: How do I easily add
+desktop support to my existing Flutter application?
+
+The answer is that at this point, you don't. The project is still in early
+stages, and a lot of things are still in flux; if you don't already have
+experience doing desktop development on the platform(s) you want to add,
+this project is probably not ready for you to use it yet. The focus is currently
+on improving core functionality, not on ease of use. Neither the API surface nor
+the project structure are stable, and no attempt will be made to provide
+supported migration paths as things change.
+
+However, if you want to try out an existing Flutter application running on the
+desktop even with those caveats, and don't have experience with desktop
+development, here are two approaches that might work for you.
+
+With either approach, be sure to follow the [main README](README.md) and
+[library README](library/README.md) instructions on setting up prerequisites
+and adjusting your Flutter application.
+
+## Replace the 'example' Flutter Code
+
+Since `example/` is already configured to run on all the platforms this project
+supports, you can swap in your project's Dart code, `pubspec.yaml`, resources,
+etc., then follow the [normal directions](example/README.md) for building the
+example application on your platform.
+
+This will be the easiest approach to keep working as the project changes, but
+requires that you essentially wrap your whole application in a
+flutter-desktop-embedding checkout.
+
+## Copy the '\*\_fde' Directories
+
+Starting from the example projects means you don't have to create projects from
+scratch, and since they are self-contained they can be added to an existing
+project without needing to move it. However, because the projects build
+the flutter-desktop-embedding libraries from source, they contain relative paths
+to the flutter-desktop-embedding projects and tools they depend on. You will
+need to update those paths in order for the projects to work. On Linux, the
+variables you will need to change are documented in the Makefile. On macOS and
+Windows, you will need some familiarity with Xcode and Visual Studio
+respectively to make the changes.
+
+With this approach, you should expect breakage when you update the
+flutter-desktop-embedding reposity; when that happens you will need to look at
+what has changed in the example projects and update your copies accordingly, or
+start over with fresh copies and adjust the paths again.

README.md

@@ -11,14 +11,17 @@ optional plugins to access other native platform functionality.
 
 ## How to Use This Code
 
+_If you have an existing Flutter app and just want to get it running, see
+the [quick start](Quick-Start.md) page before continuing._
+
 ### Setting Up
 
 The tooling and build infrastructure for this project requires that you have
 a Flutter tree in the same parent directory as the clone of this project:
 
 ```
 <parent dir>
-  ├─ flutter (from http://github.com/flutter/flutter)
+  ├─ flutter (from https://github.com/flutter/flutter)
   └─ flutter-desktop-embedding (from https://github.com/google/flutter-desktop-embedding)
 ```
 

build/ci/install_flutter

@@ -16,8 +16,8 @@
 
 set -e
 
-readonly CHANNEL="stable"
-readonly VERSION="1.0.0"
+readonly CHANNEL="dev"
+readonly VERSION="1.1.8"
 
 if [[ "${TRAVIS_OS_NAME}" == "linux" ]]; then
   readonly FLUTTER_OS="linux"

example/README.md

@@ -3,36 +3,52 @@
 This application shows an example of how to use the embedding library on each
 platform including build dependencies, resource bundling, and using plugins.
 
+In this example, the platform-specific code lives in `<platform>_fde`. For
+instance, the macOS project is in macos\_fde. This follows the pattern of
+the `android/` and `ios/` directories in a typical Flutter application (with
+`_fde` suffixes to avoid confusion or collisions if desktop support is added
+to Flutter itself). There's no requirement to use the same names in your
+project, or even to put them in the Flutter application directory.
+
 The example application is intended to be a starting point, rather than an
 authoritative example. For instance, you might use a different build system,
-package resources differently, etc.
+package resources differently, etc. If you are are adding Flutter to an
+existing desktop application, you might instead put the Flutter application code
+inside your existing project structure.
 
 It also serves as a simple test environment for the plugins that are part of
 this project, and built-in event handling, so is a collection of unrelated
 functionality rather than a usable application.
 
 ## Building and Running the Example
 
-Since the example is meant to show how the library would actually be used, it
-deliberately uses platform-specific build systems that are separate from the
-rest of the project's build system.
+There is currently no tool that abstracts the platform-specific builds the
+way `flutter build` or `flutter run` does for iOS and Android, so you will need
+to follow the platform-specific build instructions for your platform below.
 
-The examples do build the library from source, so you will need to ensure you
+The examples build the library from source, so you will need to ensure you
 have all the dependencies for
 [building the library on your platform](../library/README.md) before continuing.
 
 ### Linux
 
-Run `make` under `linux/`. The example binary and its resources will be
-in `out/`, and can be run from there:
+Run `make -C example/linux_fde/`. The example binary and its resources will be
+in `example/build/linux_fde`, and can be run from there:
+
+```
+$ ./example/build/linux_fde/debug/flutter_embedder_example
+```
+
+To build a version with Dart asserts disabled (and thus no DEBUG banner),
+run `make BUILD=release` instead, then launch it with:
 
 ```
-$ ./out/flutter_embedder_example
+$ ./example/build/linux_fde/release/flutter_embedder_example
 ```
 
 ### macOS
 
-Open the ExampleEmbedder Xcode project under `macos/`, and build and run the
+Open the ExampleEmbedder Xcode project under `macos_fde/`, and build and run the
 example application target.
 
 #### Note
@@ -50,11 +66,11 @@ to a XIB in your own project:
 
 ### Windows
 
-Open the `Example Embedder` Visual Studio solution file under `windows\` and
+Open the `Example Embedder` Visual Studio solution file under `windows_fde\` and
 build the GLFW Example project.
 
 The resulting binary will be in `bin\x64\$(Configuration)\GLFW Example\`. It
-currently uses relative paths so must be run from the `windows\` directory:
+currently uses relative paths so must be run from the `windows_fde\` directory:
 
 ```
 > ".\bin\x64\$(Configuration)\GLFW Example\GLFW Example.exe"

example/analysis_options.yaml

@@ -0,0 +1 @@
+include: ../analysis_options.yaml

example/linux/Makefile → example/linux_fde/Makefile

@@ -12,12 +12,30 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# Example-specific variables.
+# To modify this Makefile for a different application, these are the values
+# that are mostly likely to need to be changed.
+
+# The location of the flutter-desktop-embedding repository.
+FDE_ROOT=$(CURDIR)/../..
+# The C++ code for the embedder application.
+SOURCES=flutter_embedder_example.cc
+# Plugins to include (from the flutter-desktop-embedding plugins/ directory).
+PLUGIN_NAMES=color_panel file_chooser menubar
+
+
+# Default build type. For a release build, set BUILD=release.
+# Currently this only sets NDEBUG, which is used to control the flags passed
+# to the Flutter engine in the example shell, and not the complation settings
+# (e.g., optimization level) of the C++ code.
+BUILD:=debug
+
 # Dependency locations
-PROJECT_ROOT=$(CURDIR)/../..
-FLUTTER_EMBEDDER_LIB_DIR=$(PROJECT_ROOT)/library/linux
-FLUTTER_APP_DIR=$(PROJECT_ROOT)/example/flutter_app
-PLUGINS_DIR=$(PROJECT_ROOT)/plugins
-TOOLS_DIR=$(PROJECT_ROOT)/tools
+FLUTTER_APP_DIR=$(CURDIR)/..
+FLUTTER_APP_BUILD_DIR=$(FLUTTER_APP_DIR)/build
+FLUTTER_EMBEDDER_LIB_DIR=$(FDE_ROOT)/library/linux
+PLUGINS_DIR=$(FDE_ROOT)/plugins
+TOOLS_DIR=$(FDE_ROOT)/tools
 FLUTTER_DIR=$(shell $(TOOLS_DIR)/flutter_location)
 
 # Libraries
@@ -27,7 +45,6 @@ FLUTTER_EMBEDDER_LIB=$(FLUTTER_EMBEDDER_LIB_DIR)/lib$(FLUTTER_EMBEDDER_LIB_NAME)
 FLUTTER_ENGINE_LIB_NAME=flutter_engine
 FLUTTER_ENGINE_LIB=$(FLUTTER_EMBEDDER_LIB_DIR)/lib$(FLUTTER_ENGINE_LIB_NAME).so
 
-PLUGIN_NAMES=color_panel file_chooser menubar
 PLUGIN_LIB_NAME_PREFIX=flutter_embedder_
 PLUGIN_LIBS=$(foreach plugin,$(PLUGIN_NAMES)\
 	,$(PLUGINS_DIR)/$(plugin)/linux/lib$(PLUGIN_LIB_NAME_PREFIX)$(plugin).so)
@@ -37,7 +54,7 @@ ALL_LIBS=$(FLUTTER_EMBEDDER_LIB) $(FLUTTER_ENGINE_LIB) $(PLUGIN_LIBS)
 # Headers
 PLUGIN_DIRS=$(patsubst %,$(PLUGINS_DIR)/%/linux,$(PLUGIN_NAMES))
 LIBRARY_DIRS=$(FLUTTER_EMBEDDER_LIB_DIR) $(PLUGIN_DIRS)
-INCLUDE_DIRS=$(patsubst %,%/include,$(LIBRARY_DIRS)) $(PROJECT_ROOT)/library/include
+INCLUDE_DIRS=$(patsubst %,%/include,$(LIBRARY_DIRS)) $(FDE_ROOT)/library/include
 
 # Tools
 BUILD_ASSETS_BIN=$(TOOLS_DIR)/build_flutter_assets
@@ -47,10 +64,10 @@ FLUTTER_BIN=$(FLUTTER_DIR)/bin/flutter
 ICU_DATA_NAME=icudtl.dat
 ICU_DATA_SOURCE=$(FLUTTER_DIR)/bin/cache/artifacts/engine/linux-x64/$(ICU_DATA_NAME)
 FLUTTER_ASSETS_NAME=flutter_assets
-FLUTTER_ASSETS_SOURCE=$(FLUTTER_APP_DIR)/build/$(FLUTTER_ASSETS_NAME)
+FLUTTER_ASSETS_SOURCE=$(FLUTTER_APP_BUILD_DIR)/$(FLUTTER_ASSETS_NAME)
 
 # Output bundle structure and targets
-OUT_DIR=$(CURDIR)/out
+OUT_DIR=$(FLUTTER_APP_BUILD_DIR)/linux_fde/$(BUILD)
 OUT_DATA_DIR=$(OUT_DIR)/data
 OUT_LIB_DIR=$(OUT_DIR)/lib
 
@@ -60,9 +77,7 @@ ALL_LIBS_OUT=$(foreach lib,$(ALL_LIBS),$(OUT_LIB_DIR)/$(notdir $(lib)))
 
 # Overrides for the optional GN build.
 ifdef USE_GN
-GN_OUT_DIR=$(PROJECT_ROOT)/out
-# Use GN's out dir even though this isn't a GN build, to group build output.
-OUT_DIR=$(GN_OUT_DIR)/example
+GN_OUT_DIR=$(FDE_ROOT)/out
 
 # The GN build places all libraries at the top level of the output directory.
 FLUTTER_EMBEDDER_LIB=$(GN_OUT_DIR)/lib$(FLUTTER_EMBEDDER_LIB_NAME).so
@@ -83,7 +98,9 @@ endif
 
 # Build settings
 CXX=g++ -std=c++14
-CXXFLAGS=-Wall -Werror $(shell pkg-config --cflags jsoncpp glfw3)
+CXXFLAGS.release=-DNDEBUG
+CXXFLAGS=-Wall -Werror $(shell pkg-config --cflags jsoncpp glfw3) \
+				 $(CXXFLAGS.$(BUILD))
 CPPFLAGS=$(patsubst %,-I%,$(INCLUDE_DIRS))
 ifdef USE_GN
 CPPFLAGS+=-DUSE_FLATTENED_INCLUDES
@@ -95,8 +112,6 @@ LDFLAGS=-L$(OUT_LIB_DIR) \
 	$(patsubst %,-l$(PLUGIN_LIB_NAME_PREFIX)%,$(PLUGIN_NAMES)) \
 	-Wl,-rpath=\$$ORIGIN/lib
 
-SOURCES=flutter_embedder_example.cc
-
 # Targets
 
 .PHONY: all

example/linux/flutter_embedder_example.cc → example/linux_fde/flutter_embedder_example.cc

@@ -24,9 +24,9 @@
 #include <menubar/menubar_plugin.h>
 
 #ifdef USE_FLATTENED_INCLUDES
-#include <flutter_desktop_embedding/embedder.h>
+#include <flutter_desktop_embedding/flutter_window_controller.h>
 #else
-#include <flutter_desktop_embedding/glfw/embedder.h>
+#include <flutter_desktop_embedding/glfw/flutter_window_controller.h>
 #endif
 
 namespace {
@@ -53,10 +53,6 @@ std::string GetExecutableDirectory() {
 }  // namespace
 
 int main(int argc, char **argv) {
-  if (!flutter_desktop_embedding::FlutterInit()) {
-    std::cerr << "Couldn't init GLFW" << std::endl;
-  }
-
   // Resources are located relative to the executable.
   std::string base_directory = GetExecutableDirectory();
   if (base_directory.empty()) {
@@ -71,26 +67,27 @@ int main(int argc, char **argv) {
 #ifdef NDEBUG
   arguments.push_back("--disable-dart-asserts");
 #endif
+
+  flutter_desktop_embedding::FlutterWindowController flutter_controller(
+      icu_data_path);
+
   // Start the engine.
-  auto window = flutter_desktop_embedding::CreateFlutterWindow(
-      640, 480, assets_path, icu_data_path, arguments);
-  if (window == nullptr) {
-    flutter_desktop_embedding::FlutterTerminate();
+  if (!flutter_controller.CreateWindow(640, 480, assets_path, arguments)) {
     return EXIT_FAILURE;
   }
 
   // Register any native plugins.
   plugins_menubar::MenubarPlugin::RegisterWithRegistrar(
-      flutter_desktop_embedding::GetRegistrarForPlugin(
-          window, "plugins_menubar::MenubarPlugin"));
+      flutter_controller.GetRegistrarForPlugin(
+          "plugins_menubar::MenubarPlugin"));
   plugins_color_panel::ColorPanelPlugin::RegisterWithRegistrar(
-      flutter_desktop_embedding::GetRegistrarForPlugin(
-          window, "plugins_color_panel::ColorPanelPlugin"));
+      flutter_controller.GetRegistrarForPlugin(
+          "plugins_color_panel::ColorPanelPlugin"));
   plugins_file_chooser::FileChooserPlugin::RegisterWithRegistrar(
-      flutter_desktop_embedding::GetRegistrarForPlugin(
-          window, "plugins_file_chooser::FileChooserPlugin"));
+      flutter_controller.GetRegistrarForPlugin(
+          "plugins_file_chooser::FileChooserPlugin"));
 
-  flutter_desktop_embedding::FlutterWindowLoop(window);
-  glfwTerminate();
+  // Run until the window is closed.
+  flutter_controller.RunEventLoop();
   return EXIT_SUCCESS;
 }