Skip to content

Commit

Permalink
readme additions
Browse files Browse the repository at this point in the history
  • Loading branch information
jakemac53 committed Mar 11, 2016
1 parent 6f36cda commit 476fa92
Showing 1 changed file with 55 additions and 0 deletions.
55 changes: 55 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 476fa92

Please sign in to comment.