From 476fa920d9d9630855566abf48ca5886385ea4e0 Mon Sep 17 00:00:00 2001 From: Jacob MacDonald Date: Fri, 11 Mar 2016 13:27:07 -0800 Subject: [PATCH] readme additions --- README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/README.md b/README.md index a28b98f3b..09d4f284c 100644 --- a/README.md +++ b/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