Add a description of the packages used to implement a plugin

Change-Id: Ibb5207e93e7c12560cd9be6845c63a3d50e23df5
Reviewed-on: https://dart-review.googlesource.com/18780
Commit-Queue: Brian Wilkerson <brianwilkerson@google.com>
Reviewed-by: Devon Carew <devoncarew@google.com>

pkg/analyzer_plugin/doc/tutorial/package_structure.md

@@ -0,0 +1,93 @@
+# Package Structure
+
+Plugins are used by tools that want to allow external contributions to the
+results being produced by that tool. At the moment, the analysis server is the
+only tool that supports plugins, but we intend to add plugin support to the
+command-line analyzer and possibly other tools as well. For that reason,
+throughout this document we will generically refer to the tool running the
+plugins as simply the _tool_.
+
+In order to describe the way tools use plugins, we need to refer to four
+different packages. In order to keep the discussion clear, we will refer to
+those packages as the target package, the host package, the bootstrap package,
+and the plugin package. (If you're not familiar will packages, you should read
+about the Dart [package manager][pub].)
+
+The _target package_ is the package for which the tool is producing analysis
+results. If the tool is the analysis server, this is a package that the user has
+opened in the client and is actively developing.
+
+The _host package_ is a package that contains the information necessary to find
+and run the plugin. Specifically, the host package contains the bootstrap
+package. In order for the tool to find and use the host package, the target
+package must have a dependency on the host package. This can be either a normal
+dependency or a dev dependency.
+
+The _bootstrap package_ is a small package embedded within the host package that
+is used to load the plugin package.
+
+The _plugin package_ is the package that contains the actual implementation of
+the plugin.
+
+While you could technically merge the bootstrap and plugin packages, we
+recommend this structure because it minimizes the number of additional files
+that need to be downloaded by users who do not choose to enable the hosted
+plugin.
+
+As a concrete example, the angular package has a plugin associated with it. In
+order to implement this, the angular package has a bootstrap package embedded
+within it. When a target package (a package implementing a web app) has a
+dependency on the angular package, it can list 'angular' as an approved host
+package and the angular plugin will be run.
+
+## Plugin Discovery
+
+Plugins are used by a tool to analyze the target package only if the tool is
+explicitly told to run them. Tools look for a list of approved host packages in
+the analysis options file (`analysis_options.yaml`) associated with the target
+package. The list has the form:
+
+```yaml
+analyzer:
+  plugins:
+    - host_package_1
+    - host_package_2
+```
+
+If a listed host package can be found (via the `.packages` file associated with
+the target package), then the tool looks in the host package for the folder
+`<host_package>/tools/analysis_plugin`. If that directory exists and contains a
+valid bootstrap package, then the bootstrap package is run as a plugin.
+
+## Bootstrap Package Structure
+
+The other packages described above can have any valid package structure, but the
+bootstrap package is required to have two specific files.
+
+First, it must have a file named `tools/analyzer_plugin/pubspec.yaml` that can
+be used by the [`pub`][pub] command to produce a `.packages` file describing how
+to resolve the `package:` URIs found in it. Typically, the only dependency that
+needs to be included is a dependency on the plugin package.
+
+Second, it must have a file named `tools/analyzer_plugin/bin/plugin.dart` that
+contains the entry point for the plugin. Every plugin will be run in a separate
+isolate. As a result, the entry point must have the following signature:
+
+```dart
+void main(List<String> args, SendPort sendPort) {
+  // Invoke the real main method in the plugin package. 
+}
+```
+
+The body of `main` should typically be a single line that invokes a method or
+function within the plugin package that will create and start the plugin.
+
+## Plugin Execution
+
+When a bootstrap package is to be run, the contents of the directory containing
+the bootstrap package are copied to a temporary directory, the [`pub`][pub]
+command is run in that directory to produce a `.packages` file for the bootstrap
+package, and the file `tools/analysis_plugin/bin/plugin.dart` is run in its own
+isolate.
+
+[pub]:https://www.dartlang.org/tools/pub/get-started

pkg/analyzer_plugin/doc/tutorial/tutorial.md

@@ -1,9 +1,10 @@
 # Building a Plugin
 
 This is the table of contents for a set of pages that describe how to implement
-a plugin. You should probably read the [Introduction][introduction] and
-[Getting Started][gettingStarted] pages first, but the remaining pages can be
-read as you attempt to implement the described functionality.
+a plugin. You should probably read the [Introduction][introduction],
+[Package Structure][packageStructure] and [Getting Started][gettingStarted]
+pages first, but the remaining pages can be read when you decide to implement
+the described functionality.
 
 ## Pages
 
@@ -12,6 +13,9 @@ The following is a list of the pages available in this tutorial.
 [Introduction][introduction] -
 What is a plugin and what can it do?
 
+[Package Structure][packageStructure] -
+How the code for a plugin is structured into packages.
+
 [Getting Started][gettingStarted] -
 How to write a minimal plugin.
 
@@ -49,3 +53,4 @@ How to provide support for code folding.
 [navigation]: navigation.md
 [occurrences]: occurrences.md
 [outline]: outline.md
+[packageStructure]: package_structure.md