readme additions

README.md

@@ -4,6 +4,61 @@ This package provides an way of generating files using Dart code, outside of
 `pub`. These files are generated directly on disk in the current package folder,
 and rebuilds are _incremental_.
 
+## Differences between the `build` package and `pub`.
+
+You might be asking, why use this package instead of a pub `Transformer`? There
+are a few key differences that make this package better for some use cases.
+
+### Outputs
+
+Pub will only ever output files into your `build` directory, and pub serve only
+ever outputs them into an in memory file system. With the `build` package, you
+can output files anywhere in the current package.
+
+This enables you to generate dart files which are imported by your project,
+without getting any warnings about missing files from the analyzer. At the same
+time it enables you to easily go explore those files in your editor, and set
+breakpoints inside those files.
+
+### Inputs
+
+With `build`, you can use any file from any package you depend on as a primary
+input, where with `pub` you can only use files from your current package.
+
+### Consistency
+
+You can't overwrite any pre-existing files using `build`, you can only generate
+new ones.
+
+In pub a transformer could overwrite a file any number of times, and this can
+lead to confusion and difficulty when debugging, especially with source maps.
+
+### Incremental builds
+
+The `build` package does incremental builds whenever possible. It may decide to
+do a full rebuild due to changes in your build script (or one of its deps), or
+if you delete the cache folder, but those things shouldn't happen often.
+
+With `pub`, some transformations on your package dependencies may be cached, but
+any transformations on your current package are always redone each time you call
+`pub build` or `pub serve`. In serve mode it will do incremental builds once the
+first build has run, but if you restart it then you have to start over from
+scratch.
+
+### Execution modes and reflection
+
+Most frameworks that use reflection today enable running in two different modes,
+one which uses `dart:mirrors` for development in dartium, and one which uses
+static code generated by a `Transformer` for deployment. All features that use
+reflection have to be implemented in both modes, and bugs might exist in only
+one mode. This all ends up resulting in obscure deployment time only issues,
+as well as a lot of wasted cycles testing the same app in multiple different
+modes.
+
+With `build`, you can eliminate entirely the `dart:mirrors` mode. You are always
+using the generated code, all the time. This makes it easier on framework devs,
+and easier on users who have fewer modes to support.
+
 ## Running Builds
 
 In order to run a build, you write a script which uses one of the three top