A build system for Dart code generation and modular compilation.
Standalone generator and watcher for Dart using
build_runner package provides a concrete way of generating files using
Dart code, outside of tools like
pub serve/build, files are
always generated directly on disk, and rebuilds are incremental - inspired by
tools such as Bazel.
NOTE: Are you a user of this package? You may be interested in simplified user-facing documentation, such as our getting started guide.
When the packages providing
Builders are configured with a
they are designed to be consumed using an generated build script. Most builders
should need little or no configuration, see the documentation provided with the
Builder to decide whether the build needs to be customized. If it does you may
also provide a
build.yaml with the configuration. See the
package:build_config README for more information on this file.
To have web code compiled to js add a
Built-in Commands #
build_runner package exposes a binary by the same name, which can be
pub run build_runner <command>.
The available commands are
build: Runs a single build and exits.
watch: Runs a persistent build server that watches the files system for edits and does rebuilds as necessary.
serve: Same as
watch, but runs a development server as well.
- By default this serves the
testdirectories, on port
8081respectively. See below for how to configure this.
- By default this serves the
test: Runs a single build, creates a merged output directory, and then runs
pub run test --precompiled <merged-output-dir>. See below for instructions on 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.
--assume-tty: Enables colors and interactive input when the script does not appear to be running directly in a terminal, for instance when it is a subprocess.
--delete-conflicting-outputs: Assume conflicting outputs in the users package are from previous builds, and skip the user prompt that would usually be provided.
--[no-]fail-on-severe: Whether to consider the build a failure on an error logged. By default this is false.
Some commands also have additional options:
--hostname: The host to run the server on.
--live-reload: Enables automatic page reloading on rebuilds. Can't be used together with
--hot-reload: Enables automatic reloading of changed modules on rebuilds. See hot-module-reloading for more info. Can't be used together with
Trailing args of the form
<directory>:<port> are supported to customize what
directories are served, and on what ports.
For example to serve the
web directories on ports 8000 and 8001
you would do
pub run build_runner serve example:8000 web:8001.
The test command will forward any arguments after an empty
-- arg to the
pub run test command.
For example if you wanted to pass
-p chrome you would do
pub run build_runner test -- -p chrome.
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.
- You may output files anywhere in the current package.
NOTE: When a
hideOutput: trueit may output under the
libfolder of any 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 previous
BuilderApplications'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
# 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
Builders may provide a recommendation for
this as well.
Legacy Usage #
If the generated script does not do everything you need it's possible to
manually write one. With this approach every package which uses a
Builder must have it's own script, they cannot be reused
from other packages. A package which defines a
Builder may have an
example you can reference, but a unique script must be written for the consuming
packages as well. You can reference the generated script at
.dart_tool/build/entrypoint/build.dart for an example.
Your script should use one of the following functions defined by this library:
run: Use the same argument parsing as the generated approach.
build: Run a single build and exit.
watch: Continuously run builds as you edit files.
watch have a required
argument which is a
List<BuilderApplication>. These correspond to the
BuilderDefinition class from
applyToRoot to create instances of this class. These will be translated into
actions by crawling through dependencies. The order of this list is important.
Each Builder may read the generated outputs of any Builder that ran on a package
earlier in the dependency graph, but for the package it is running on it may
only read the generated outputs from Builders earlier in the list of
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.
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.
All pull requests are validated against travis, and must pass. The
build_runner package lives in a mono repository with other
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