Added tool support for running snapshotted Dart scripts. (#1820)

Since tools are run so often, it makes sense to use snapshots to run them, so this makes it so that Dartdoc creates a snapshot automatically of a tool the first time it is run, and then uses that snapshot from then on.

See the README.md for the new instructions, but basically, it creates a snapshot in a tempdir the first time the tool is run, using the first time arguments as training arguments for the compiler. The second time and beyond, it is run using the snapshot. This results in about a 20-100x speedup in startup time for the tool invocations. If you'd rather build and use your own snapshots, it does recognize the .snapshot suffix, and will just use that one instead of generating its own.

In addition, I added the ability to run a "setup" command before the first time a tool runs. This would allow generation of script code, or fetching one-time information needed for the tool to run.

I also added some more tests for things that weren't broken, but also weren't tested, and converted the tool_runner test to get its information from parsing a YAML block instead of setting up the map programmatically (more code coverage that way, and I can test the snapshotted executables that way).

Author: gspencergoog

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.24.2-dev
+* Added support for automatic snapshotting of external tools (i.e. for {@tool}
+  directives) written in Dart. 
+
 ## 0.24.1
 * Added more metadata (element name, project name, etc.) to external tool invocations.
   (#1801)

README.md

@@ -259,11 +259,15 @@ dartdoc:
   tools:
     drill:
       command: ["bin/drill.dart"]
+      setup_command: ["bin/setup.dart"]
       description: "Puts holes in things."
     echo:
       macos: ['/bin/sh', '-c', 'echo']
+      setup_macos: ['/bin/sh', '-c', 'setup.sh']
       linux: ['/bin/sh', '-c', 'echo']
+      setup_linux: ['/bin/sh', '-c', 'setup.sh']
       windows: ['C:\\Windows\\System32\\cmd.exe', '/c', 'echo']
+      setup_windows: ['/bin/sh', '-c', 'setup.sh']
       description: 'Works on everything'
 ```
 
@@ -272,16 +276,32 @@ that are common among all executions. If the first element of this list is a
 filename that ends in `.dart`, then the dart executable will automatically be
 used to invoke that script. The `command` defined will be run on all platforms.
 
-The `macos`, `linux`, and `windows` tags are used to describe the commands to
-be run on each of those platforms.
+If the `command` is a Dart script, then the first time it is run, a snapshot
+will be created using the input and first-time arguments as training arguments,
+and will be run from the snapshot from then on. Note that the `Platform.script`
+property will point to the snapshot location during the snapshot runs. You can
+obtain the original `.dart` script location in a tool by looking at the
+`TOOL_COMMAND` environment variable.
+
+The `setup_command` tag is used to describe a command executable, and any
+options, for a command that is run once before running a tool for the first
+time. If the first element of this list is a filename that ends in `.dart`, then
+the dart executable will automatically be used to invoke that script. The
+`setup_command` defined will be run on all platforms. If the setup command is a
+Dart script, then it will be run with the Dart executable, but will not be
+snapshotted, as it will only be run once.
+
+The `macos`, `linux`, and `windows` tags are used to describe the commands to be
+run on each of those platforms, and the `setup_macos`, `setup_linux`, and
+`setup_windows` tags define setup commands for their respective platforms.
 
 The `description` is just a short description of the tool for use as help text. 
 
 Only tools which are configured in the `dartdoc_options.yaml` file are able to
 be invoked.
 
-To use the tools in comment documentation, use the `{@tool <name> [<options> ...] [$INPUT]}`
-directive to invoke the tool:
+To use the tools in comment documentation, use the `{@tool <name> [<options>
+...] [$INPUT]}` directive to invoke the tool:
 
 ```dart
 /// {@tool drill --flag --option="value" $INPUT}
@@ -301,6 +321,27 @@ the equivalent of having the following comment in the code:
 /// # `This is the text that will be sent to the tool as input.`
 ```
 
+#### Tool Environment Variables
+
+Tools have a number of environment variables available to them. They will be
+interpolated into any arguments given to the tool as `$ENV_VAR` or `$(ENV_VAR)`,
+as well as available in the process environment.
+
+- `SOURCE_LINE`: The source line number in the original source code.
+- `SOURCE_COLUMN`: The source column in the original source code.
+- `SOURCE_PATH`: The relative path from the package root to the original source file.
+- `PACKAGE_PATH`: The path to the package root.
+- `PACKAGE_NAME`: The name of the package.
+- `LIBRARY_NAME`: The name of the library, if any.
+- `ELEMENT_NAME`: The name of the element that this doc is attached to.
+- `TOOL_COMMAND`: The path to the original `.dart` script or command executable.
+- `DART_SNAPSHOT_CACHE`: The path to the directory containing the snapshot files
+   of the tools. This directory will be removed before Dartdoc exits.
+- `DART_SETUP_COMMAND`: The path to the setup command script, if any.
+- `INVOCATION_INDEX`: An index for how many times a tool directive has been
+  invoked on the current dartdoc block. Allows multiple tool invocations on the
+  same block to be differentiated.
+
 ### Injecting HTML
 
 It happens rarely, but sometimes what you really need is to inject some raw HTML

bin/dartdoc.dart

@@ -71,23 +71,28 @@ void main(List<String> arguments) async {
   Dartdoc dartdoc = await Dartdoc.withDefaultGenerators(config);
 
   dartdoc.onCheckProgress.listen(logProgress);
-  await Chain.capture(() async {
-    await runZoned(() async {
-      DartdocResults results = await dartdoc.generateDocs();
-      logInfo('Success! Docs generated into ${results.outDir.absolute.path}');
-    },
-        zoneSpecification: new ZoneSpecification(
-            print: (Zone self, ZoneDelegate parent, Zone zone, String line) =>
-                logPrint(line)));
-  }, onError: (e, Chain chain) {
-    if (e is DartdocFailure) {
-      stderr.writeln('\nGeneration failed: ${e}.');
-      exit(1);
-    } else {
-      stderr.writeln('\nGeneration failed: ${e}\n${chain.terse}');
-      exit(255);
-    }
-  });
+  try {
+    await Chain.capture(() async {
+      await runZoned(() async {
+        DartdocResults results = await dartdoc.generateDocs();
+        logInfo('Success! Docs generated into ${results.outDir.absolute.path}');
+      },
+          zoneSpecification: new ZoneSpecification(
+              print: (Zone self, ZoneDelegate parent, Zone zone, String line) =>
+                  logPrint(line)));
+    }, onError: (e, Chain chain) {
+      if (e is DartdocFailure) {
+        stderr.writeln('\nGeneration failed: ${e}.');
+        exit(1);
+      } else {
+        stderr.writeln('\nGeneration failed: ${e}\n${chain.terse}');
+        exit(255);
+      }
+    });
+  } finally {
+    // Clear out any cached tool snapshots.
+    SnapshotCache.instance.dispose();
+  }
 }
 
 /// Print help if we are passed the help option.

lib/dartdoc.dart

@@ -181,8 +181,12 @@ class Dartdoc extends PackageBuilder {
           "dartdoc could not find any libraries to document. Run `pub get` and try again.");
     }
 
-    if (dartdocResults.packageGraph.packageWarningCounter.errorCount > 0) {
-      throw new DartdocFailure("dartdoc encountered errors while processing");
+    final int errorCount =
+        dartdocResults.packageGraph.packageWarningCounter.errorCount;
+    if (errorCount > 0) {
+      dartdocResults.packageGraph.flushWarnings();
+      throw new DartdocFailure(
+          "dartdoc encountered $errorCount} errors while processing.");
     }
 
     return dartdocResults;