Update READMEs

Author: stuartmorgan-g

example/README.md

@@ -66,21 +66,14 @@ to a XIB in your own project:
 
 ### Windows
 
-Open the `Example Embedder` Visual Studio solution file under `windows_fde\` and
-build the GLFW Example project.
+Open the `Example Embedder` Visual Studio solution file under `windows_fde\` to
+build and run 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_fde\` directory:
+The resulting binary will be in
+`example\build\windows_fde\x64\$(Configuration)\GLFW Example\`. It currently
+uses relative paths so if you run it manually it must be run from the
+`example\windows_fde\` directory. E.g.:
 
 ```
-> ".\bin\x64\$(Configuration)\GLFW Example\GLFW Example.exe"
+> "..\build\windows_fde\x64\Debug\GLFW Example\GLFW Example.exe"
 ```
-
-e.g.:
-
-```
-> ".\bin\x64\Debug Dynamic Library\GLFW Example\GLFW Example.exe"
-```
-
-Or you can use Visual Studio's inbuilt debugger to build and run the
-example application automatically.

library/GN.md

@@ -37,6 +37,8 @@ the ICU data from the Flutter engine.
 
 #### Dependencies
 
+**Libraries**
+
 First you will need to install the relevant library dependencies:
 *   GLFW3
 *   GTK 3
@@ -52,6 +54,8 @@ $ sudo apt-get install libglfw3-dev libepoxy-dev libjsoncpp-dev libgtk-3-dev \
       libx11-dev pkg-config
 ```
 
+**GN**
+
 You will need to install the build tools if you don't already have them:
 * [ninja](https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages)
 * [gn](https://gn.googlesource.com/gn/)
@@ -75,9 +79,11 @@ Public headers will be in `out/include/`; you should point dependent
 builds at that location rather than the `include/` directories in the
 source tree.
 
-See
-[flutter_window_controller.h](include/flutter_desktop_embedding/glfw/flutter_window_controller.h)
-for details on calling into the library.
+The shared library provides a minimal C interface, but the recommended
+approach is to add the code in `out/fde_cpp_library/` to your project, to
+interact with the library using richer APIs. See
+[flutter_window_controller.h](/library/common/client_wrapper/include/flutter_desktop_embedding/glfw/flutter_window_controller.h)
+and the other headers under that directory for details.
 
 ### macOS
 
@@ -107,6 +113,8 @@ so you do not need to include that framework in your project directly.
 
 #### Dependencies
 
+**Visual Studio**
+
 You must have a copy of Visual Studio installed, and the command line build
 tools, such as `vcvars64.bat`, must be in your path. They are found under:
 
@@ -120,17 +128,45 @@ e.g.:
 C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build
 ```
 
+**jsoncpp**
+
+jsoncpp must be downloaded to `third_party/jsoncpp\src`. You can use
+`tools/dart_tools/bin/fetch_jsoncpp.dart` to simplify this:
+
+```
+> tools\run_dart_tool.bat fetch_jsoncpp third_party\jsoncpp\src
+```
+
+**GN**
+
+You will need to install the build tools if you don't already have them:
+* [ninja](https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages)
+* [GN](https://gn.googlesource.com/gn/)
+
+Ensure that both binaries are in your path.
+
 #### Using the Library
 
-Build the GLFW Library project under `windows/` in Visual Studio into a static
-or dynamic library, then link `flutter_embedder.lib` into your binary and make
-sure `flutter_window_controller.h` is in your include paths. Also ensure that
-the `flutter_engine.dll`, and if using a dynamic library
-`flutter_embedder.dll`, are in valid DLL include paths.
+To build the library, run the following at the root of this repository:
+
+```
+$ tools\gn_dart gen out
+$ ninja -C out flutter_embedder
+```
+Subsequent builds only require the `ninja` step, as the build will automatically
+re-run GN generation if necessary.
 
-The output files are located in `bin\x64\$(Configuration)\GLFW Library\`.
+The build results will be in the top-level `out\` directory. You will need to
+link `libflutter_embedder.dll` and `libflutter_engine.dll` into your binary.
+Public headers will be in `out/include/`; you should point dependent
+builds at that location rather than the `include/` directories in the
+source tree.
 
-_Note: There is also a [GN build](GN.md) available as an alternative._
+The DLL provides a minimal C interface, but the recommended
+approach is to add the code in `out\fde_cpp_library\` to your project, to
+interact with the library using richer APIs. See
+[flutter_window_controller.h](/library/common/client_wrapper/include/flutter_desktop_embedding/glfw/flutter_window_controller.h)
+and the other headers under that directory for details.
 
 ## Caveats