Standalone generator and watcher for Dart usingpackage:build.

Thebuild_runner package provides a concrete way of generating files usingDart code. Files are always generated directly on disk, andrebuilds areincremental - inspired by tools such asBazel.

NOTE: Are you a user of this package? You may be interested insimplified user-facing documentation, such as ourgetting started guide andfaq.

• Installation
• Usage
  • Built-in commands
  • Inputs
  • Outputs
  • Source control
  • Publishing packages
• Docs
• Contributing
  • Testing

Installation#

This package is intended to support development of Dart projects withpackage:build. In general, add it to yourpubspec.yamlas adev_dependencies by running the following command.

$ dart pub add dev:build_runner

Usage#

When the packages providingBuilders are configured with abuild.yaml filethey are designed to be consumed using an generated build script. Most buildersshould need little or no configuration, see the documentation provided with theBuilder to decide whether the build needs to be customized. If it does you mayalso provide abuild.yaml with the configuration. See thepackage:build_config README for more information on this file.

To have web code compiled to js add adev_dependency onbuild_web_compilers.

Docs#

More comprehensive documentation is stored in this repository, under thedocs directory. If you find something is undocumented, pleasefile an issue.

Built-in Commands#

Thebuild_runner package exposes a binary by the same name, which can beinvoked usingdart run build_runner <command>.

The available commands arebuild,watch,serve, andtest.

• build: Runs a single build and exits.
• watch: Runs a persistent build server that watches the files system foredits and does rebuilds as necessary.
• serve: Same aswatch, but runs a development server as well.
  • By default this serves theweb andtest directories, on port8080 and8081 respectively. See below for how to configure this.
• test: Runs a single build, creates a merged output directory, and then runsdart run test --precompiled <merged-output-dir>. See below for instructionson passing custom args to the test command.

Command Line Options

All the above commands support the following arguments:

• --help: Print usage information for the command.
• --delete-conflicting-outputs: Assume conflicting outputs in the userspackage are from previous builds, and skip the user prompt that would usuallybe provided.
• --[no-]fail-on-severe: Whether to consider the build a failure on an errorlogged. By default this is false.
• --build-filter: Build filters allow you to choose explicitly which files tobuild instead of building entire directories. See further documentation onthis featurehere.

Some commands also have additional options:

serve

• --hostname: The host to run the server on.
• --live-reload: Enables automatic page reloading on rebuilds.

Trailing args of the form<directory>:<port> are supported to customize whatdirectories are served, and on what ports.

For example to serve theexample andweb directories on ports 8000 and 8001you would dodart run build_runner serve example:8000 web:8001.

test

The test command will forward any arguments after an empty-- arg to thedart run test command.

For example if you wanted to pass-p chrome you would dodart run build_runner test -- -p chrome.

Inputs#

Valid inputs follow the general dart package rules. You can read any files underthe top levellib folder any package dependency, and you can read all filesfrom the current package.

In general it is best to be as specific as possible with yourInputSets,because all matching files will be checked against aBuilder'sbuildExtensions - seeoutputs for moreinformation.

Outputs#

• You may output files anywhere in the current package.

NOTE: When aBuilderApplication specifieshideOutput: true it mayoutput under thelib folder ofany package you depend on.

• Builders 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 previousBuilderApplications's outputs as an input to a lateraction.

Source control#

This package creates a top level.dart_tool folder in your package, whichshould not be submitted to your source control repository. You can seeour own.gitignore as anexample.

# Files generated by dart tools.dart_tool

When it comes togenerated files it is generally best to not submit them tosource control, but a specificBuilder may provide a recommendation otherwise.

It should be noted that if you do submit generated files to your repo then whenyou change branches or merge in changes you may get a warning on your next buildabout declared outputs that already exist. This will be followed up with aprompt to delete those files. You can typel to list the files, and then typey to delete them if everything looks correct. If you think something is wrongyou can typen to abandon the build without taking any action.

Publishing packages#

In general generated filesshould be published with your package, but thismay not always be the case. SomeBuilders may provide a recommendation forthis as well.

Legacy Usage#

If the generated script does not do everything you need it's possible tomanually write one. With this approach every package whichuses aBuilder must have it's own script, they cannot be reusedfrom other packages. A package which defines aBuilder may have anexample you can reference, but a unique script must be written for the consumingpackages as well. You can reference the generated script at.dart_tool/build/entrypoint/build.dart for an example.

Your script should therun functions defined in this library.

Configuring#

run has a required parameter which is aList<BuilderApplication>.These correspond to theBuilderDefinition class frompackage:build_config.Seeapply andapplyToRoot to create instances of this class. These will betranslated into actions by crawling through dependencies. The order of this listis important. Each Builder may read the generated outputs of any Builder thatran on a package earlier in the dependency graph, but for the package it isrunning on it may only read the generated outputs from Builders earlier in thelist ofBuilderApplications.

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 wayof knowing how that change may have affected the outputs.

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 issuefirst before implementing a large new feature or breaking an API. For smallerchanges (like documentation, minor bug fixes), just send a pull request.

Testing#

All pull requests are validated against CI, and must pass. Thebuild_runner package lives in a mono repository with otherbuild packages,andall of the following checks must pass foreach package.

Ensure code passes all ouranalyzer checks:

$ dart analyze .

Ensure all code is formatted with the latestdev-channel SDK.

$ dart format .

Run all of our unit tests:

$ dart run test