Restructure the example app (#242)

* Re-organize the example app

Instead of making the platform implementations peers of the example
Flutter application, make them subdirectories of it. This matches the
structure of a standard Flutter application's mobile implementations,
and provides a better example of how to use the project to add desktop
support to an existing Flutter app.

Since interest so far has been for that use case rather than adding
Flutter to an existing application (and the current Linux and Windows
implementations don't really support the hybrid use case anyway), this
should be more reflective of how it would actually be used.

* Move Linux build output under example/build/

.appveyor.yml

@@ -20,4 +20,4 @@ install:
   - ps: build\ci\install_flutter.ps1 $env:APPVEYOR_BUILD_FOLDER\..
 
 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:

example/README.md

@@ -3,36 +3,45 @@
 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:
 
 ```
-$ ./out/flutter_embedder_example
+$ ./example/build/linux_fde/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 +59,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

@@ -15,7 +15,8 @@
 # Dependency locations
 PROJECT_ROOT=$(CURDIR)/../..
 FLUTTER_EMBEDDER_LIB_DIR=$(PROJECT_ROOT)/library/linux
-FLUTTER_APP_DIR=$(PROJECT_ROOT)/example/flutter_app
+FLUTTER_APP_DIR=$(CURDIR)/..
+FLUTTER_APP_BUILD_DIR=$(FLUTTER_APP_DIR)/build
 PLUGINS_DIR=$(PROJECT_ROOT)/plugins
 TOOLS_DIR=$(PROJECT_ROOT)/tools
 FLUTTER_DIR=$(shell $(TOOLS_DIR)/flutter_location)
@@ -47,10 +48,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
 OUT_DATA_DIR=$(OUT_DIR)/data
 OUT_LIB_DIR=$(OUT_DIR)/lib
 
@@ -61,8 +62,6 @@ 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
 
 # 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

example/macos/ExampleEmbedder.xcodeproj/project.pbxproj → example/macos_fde/ExampleEmbedder.xcodeproj/project.pbxproj

@@ -131,7 +131,7 @@
 		33CC10FE2044A7620003C045 /* FlutterEmbedderMac.xcodeproj */ = {isa = PBXFileReference; lastKnownFileType = "wrapper.pb-project"; name = FlutterEmbedderMac.xcodeproj; path = ../../library/macos/FlutterEmbedderMac.xcodeproj; sourceTree = "<group>"; };
 		33CC11122044BFA00003C045 /* ExampleWindow.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ExampleWindow.swift; sourceTree = "<group>"; };
 		33CC11162044C3600003C045 /* Example Embedder-Bridging-Header.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = "Example Embedder-Bridging-Header.h"; sourceTree = "<group>"; };
-		33CC112C20461AD40003C045 /* flutter_assets */ = {isa = PBXFileReference; lastKnownFileType = folder; name = flutter_assets; path = ../../example/flutter_app/build/flutter_assets; sourceTree = "<group>"; };
+		33CC112C20461AD40003C045 /* flutter_assets */ = {isa = PBXFileReference; lastKnownFileType = folder; name = flutter_assets; path = ../build/flutter_assets; sourceTree = "<group>"; };
 /* End PBXFileReference section */
 
 /* Begin PBXFrameworksBuildPhase section */
@@ -355,7 +355,7 @@
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 			shellPath = /bin/sh;
-			shellScript = "DEPOT_ROOT=\"$PROJECT_DIR\"/../..\n\"$DEPOT_ROOT\"/tools/build_flutter_assets \"$DEPOT_ROOT\"/example/flutter_app";
+			shellScript = "FDE_ROOT=\"$PROJECT_DIR\"/../..\n\"$FDE_ROOT\"/tools/build_flutter_assets \"$PROJECT_DIR\"/..";
 		};
 /* End PBXShellScriptBuildPhase section */
 

example/flutter_app/pubspec.yaml → example/pubspec.yaml

@@ -1,5 +1,5 @@
 name: example_flutter
-description: A new Flutter project.
+description: An example project for flutter-desktop-embedding.
 
 dependencies:
   flutter:
@@ -8,12 +8,15 @@ dependencies:
   cupertino_icons: ^0.1.0
 
   # Desktop embedder plugins.
+  # Note: In an actual project, these paths would include the
+  # path from your application to the flutter_desktop_embedding
+  # checkout.
   color_panel:
-    path: ../../plugins/color_panel
+    path: ../plugins/color_panel
   file_chooser:
-    path: ../../plugins/file_chooser
+    path: ../plugins/file_chooser
   menubar:
-    path: ../../plugins/menubar
+    path: ../plugins/menubar
 
 dev_dependencies:
   flutter_test:

example/windows/flutter_embedder_example.cpp → example/windows_fde/flutter_embedder_example.cpp

@@ -29,7 +29,7 @@ int main(int argc, char **argv) {
   // Start the engine.
   // TODO: Make paths relative to the executable so it can be run from anywhere.
   auto window = flutter_desktop_embedding::CreateFlutterWindow(
-      640, 480, "..\\..\\example\\flutter_app\\build\\flutter_assets",
+      640, 480, "..\\build\\flutter_assets",
       "..\\..\\library\\windows\\dependencies\\engine\\icudtl.dat", arguments);
   if (window == nullptr) {
     flutter_desktop_embedding::FlutterTerminate();

example/windows/scripts/build_example_app.bat → example/windows_fde/scripts/build_example_app.bat

@@ -12,4 +12,4 @@
 :: See the License for the specific language governing permissions and
 :: limitations under the License.
 @echo off
-%~dp0..\..\..\tools\build_flutter_assets %~dp0..\..\..\example\flutter_app
+%~dp0..\..\..\tools\build_flutter_assets %~dp0..\..

library/GN.md

@@ -79,8 +79,6 @@ $ ninja -C out
 To use the GN build for the depedencies of the example application, when
 running `make` for the example add `USE_GN=1` to the end of the command.
 
-The resulting binary will be in `out/example/` rather than `example/linux/out/`.
-
 #### Windows
 
 Building the example with GN is not currently supported. Follow the [Visual

plugins/README.md

@@ -57,7 +57,7 @@ plugin you want to use. For instance:
 See the example application under each platform's directory in the `example`
 directory to see an example of including optional plugins on that platform.
 
-The Flutter application under `example/flutter_app` shows examples of using
+The Flutter application under `example/` shows examples of using
 optional plugins on the Dart side.
 
 ## Writing your own plugins