build_runner 0.6.0+1 build_runner: ^0.6.0+1 copied to clipboard
Tools to write binaries that run builders.
build_runner #
Standalone generator and watcher for Dart using package:build
.
The build_runner
package provides a concrete way of generating files using
Dart code, outside of tools like pub
. Unlike pub serve/build
, files are
always generated directly on disk, and rebuilds are incremental - inspired by
tools such as Bazel.
Installation #
This package is intended to support development of Dart projects with
package:build
. In general, put it under dev_dependencies, in your
pubspec.yaml
.
dev_dependencies:
build_runner:
Usage #
To run a build, write a simple script to do the work. Every package which
uses a Builder
must have it's own script, they cannot be reused
from other packages. Often a package which defines a Builder
will
have an example you can reference, but a unique script must be written for the
consuming packages as well.
Your script should use one of the two functions defined by this library:
Configuring #
Both build
and watch
have a single required
argument, a List<BuildAction>
- each of these BuildAction
s
may run in parallel, but they may only read outputs from steps earlier in the
list.
A BuildAction
is a combination of a single
Builder
, which actually generates outputs, and a single
InputSet
, which determines what the primary inputs to that
builder will be.
Lets look at a very simple example, with a single BuildAction
. You can ignore
the CopyBuilder
for now, just know that its a Builder
which copies files:
main() async {
await build([
new BuildAction(
new CopyBuilder('.copy'),
'my_package',
inputs: ['lib/*.dart'],
),
]);
}
Copies all
*.dart
files underlib
to a corresponding*.dart.copy
.
Every time you run a build
, build_runner
checks for any changes to the
inputs specified, and reruns the CopyBuilder
for the inputs that actually
changed.
A build with multiple steps may look like:
main() async {
await build([
new BuildAction(
new CopyBuilder('.copy1'),
'my_package',
inputs: ['lib/*.dart'],
),
new BuildAction(
new CopyBuilder('.copy2'),
'my_package',
inputs: ['lib/*.dart'],
),
]);
}
Makes two copies of every
*.dart
file, a.copy1
and.copy2
.
Let's say, however, you want to use the previous output as an input to the
next build action - for example, you want to convert .md
(Markdown) to
.html
, and then convert .html
into a .png
(screenshot of the page):
main() async {
await build([
new BuildAction(
new MarkdownToHtmlBuilder(),
'my_package',
inputs: ['web/**.md'],
),
new BuildAction(
new ChromeScreenshotBuilder(),
'my_package',
inputs: ['web/**.html'],
),
]);
}
This time, all the
*.html
files will be created first, and since the nextBuildAction
is waiting for*.html
inputs, it will wait for them to be created, and then create the*.png
(screenshot) files.
NOTE: Any time you change your build script (or any of its dependencies), the next build will be a full rebuild. This is because the system has no way of knowing how that change may have affected the outputs.
Inputs #
Valid inputs follow the general dart package rules. You can read any files under
the top level lib
folder any package dependency, and you can read all files
from the current package.
In general it is best to be as specific as possible with your InputSet
s,
because all matching files will be checked against a Builder
's
buildExtensions
- see outputs for more
information.
Future versions of
build_runner
may aid in automatically generatingInputSet
s based on the builders being used! See issue #353.
Outputs #
- You may output files anywhere in the current package.
NOTE: When using the
writeToCache: true
option with eitherbuild
orwatch
, builders are allowed to output under thelib
folder of any package you depend on.
- You are not allowed to overwrite existing files, only create new ones.
- Outputs from previous builds will not be treated as inputs to later ones.
- You may use a previous
BuildAction
's outputs as an input to a later action.
Source control #
This package creates a top level .dart_tool
folder in your package, which
should not be submitted to your source control repository. You can see our own
.gitignore
as an
example.
# Files generated by dart tools
.dart_tool
When it comes to generated files it is generally best to not submit them to
source control, but a specific Builder
may provide a recommendation otherwise.
It should be noted that if you do submit generated files to your repo then when
you change branches or merge in changes you may get a warning on your next build
about declared outputs that already exist. This will be followed up with a
prompt to delete those files. You can type l
to list the files, and then type
y
to delete them if everything looks correct. If you think something is wrong
you can type n
to abandon the build without taking any action.
Publishing packages #
In general generated files should be published with your package, but this
may not always be the case. Some Builder
s may provide a recommendation for
this as well.
Contributing #
We welcome a diverse set of contributions, including, but not limited to:
- Filing bugs and feature requests
- Send a pull request
- Or, create something awesome using this API and share with us and others!
For the stability of the API and existing users, consider opening an issue first before implementing a large new feature or breaking an API. For smaller changes (like documentation, minor bug fixes), just send a pull request.
Testing #
All pull requests are validated against travis, and must pass. The
build_runner
package lives in a mono repository with other build
packages,
and all of the following checks must pass for each package.
Ensure code passes all our analyzer checks:
$ dartanalyzer .
Ensure all code is formatted with the latest dev-channel SDK.
$ dartfmt -w .
Run all of our unit tests:
$ pub run test