build_runner 0.7.7+1

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 96

build_runner

Standalone generator and watcher for Dart using package:build.
Build Status Issues related to build_runner Pub Package Version Latest Dartdocs Join the chat on Gitter

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

When the packages providing Builders are configured with a build.yaml file 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 dev_dependency on build_web_compilers.

Built-in Commands

The build_runner package exposes a binary by the same name, which can be invoked using pub run build_runner <command>.

The available commands are build, watch, serve, and test.

  • 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 web and test directories, on port 8080 and 8081 respectively. See below for how to configure this.
  • 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:

serve
  • --hostname: The host to run the server on.

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

For example to serve the example and web directories on ports 8000 and 8001 you would do pub run build_runner serve example:8000 web:8001.

test

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.

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 InputSets, because all matching files will be checked against a Builder's buildExtensions - see outputs for more information.

Outputs

  • You may output files anywhere in the current package.

NOTE: When a BuilderApplication specifies hideOutput: true it may output under the lib folder 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 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 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.

Configuring

run, build, and watch have a required argument which is a List<BuilderApplication>. These correspond to the BuilderDefinition class from package:build_config. See apply and 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 BuilderApplications.

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.

Contributing

We welcome a diverse set of contributions, including, but not limited to:

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

0.7.7+1

  • Avoid watching hosted dependencies for file changes.

0.7.7

  • The top level run method now returns an int which represents an exitCode for the command that was executed.
    • For now we still set the exitCode manually as well but this will likely change in the next breaking release. In manual scripts you should await the call to run and assign that to exitCode to be future-proofed.

0.7.6

  • Update to package:build version 0.12.0.
  • Removed the DigestAssetReader interface, the digest method has now moved to the core AssetReader interface. We are treating this as a non-breaking change because there are no known users of this interface.

0.7.5+1

  • Bug fix for using the --output flag when you have no test directory.

0.7.5

  • Add more human friendly duration printing.
  • Added the --output <dir> (or -o) argument which will create a merged output directory after each build.
  • Added the --verbose (or -v) flag which enables verbose logging.
    • Disables stack trace folding and terse stack traces.
    • Disables the overwriting of previous info logs.
    • Sets the default log level to Level.ALL.
  • Added pubspec.yaml and pubspec.lock to the whitelist for the root package sources.

0.7.4

  • Allows using files in any build targets in the root package as sources if they fall outside the hardcoded whitelist.
  • Changes to the root .packages file during watch mode will now cause the build script to exit and prompt the user to restart the build.

0.7.3

  • Added the flag --low-resources-mode, which defaults to false.

0.7.2

  • Added the flag --fail-on-severe, which defaults to false. In a future version this will default to true, which means that logging a message via log.severe will fail the build instead of just printing to the terminal. This would match the current behavior in bazel_codegen.
  • Added the test command to the build_runner binary.

0.7.1+1

  • BUG FIX: Running the build_runner binary without arguments no longer causes a crash saying Could not find an option named "assume-tty"..

0.7.1

  • Run Builders which write to the source tree before those which write to the build cache.

0.7.0

New Features

  • Added toRoot Package filter.
  • Actions are now invalidated at a fine grained level when BuilderOptions change.
  • Added magic placeholder files in all packages, which can be used when your builder doesn't have a clear primary input file.
    • For non-root packages the placeholder exists at lib/$lib$, you should declare your buildExtensions like this {r'$lib$': 'my_output_file.txt'}, which would result in an output file at lib/my_output_file.txt in the package.
    • For the root package there are also placeholders at web/$web$ and test/$test$ which should cover most use cases. Please file an issue if you need additional placeholders.
    • Note that these placeholders are not real assets and attempting to read them will result in an AssetNotFoundException.

Breaking Changes

  • Removed BuildAction. Changed build and watch to take a List<BuilderApplication>. See apply and applyToRoot to set these up.
  • Changed apply to take a single String argument - a Builder key from package:build_config rather than a separate package and builder name.
  • Changed the default value of hideOutput from false to true for apply. With applyToRoot the value remains false.
  • There is now a whitelist of top level directories that will be used as a part of the build, and other files will be ignored. For now those directories include 'benchmark', 'bin', 'example', 'lib', 'test', 'tool', and 'web'.
    • If this breaks your workflow please file an issue and we can look at either adding additional directories or making the list configurable per project.
  • Remove PackageGraph.orderedPackages and PackageGraph.dependentsOf.
  • Remove writeToCache argument of build and watch. Each apply call should specify hideOutput to keep this behavior.
  • Removed PackageBuilder and PackageBuildActions classes. Use the new magic placeholder files instead (see new features section for this release).

The following changes are technically breaking but should not impact most clients:

  • Upgrade to build_barback v0.5.0 which uses strong mode analysis and no longer analyzes method bodies.
  • Removed dependencyType, version, includes, and excludes from PackageNode.
  • Removed PackageNode.noPubspec constructor.
  • Removed InputSet.
  • PackageGraph instances enforce that the root node is the only node with isRoot == true.

0.6.1

New Features

  • Add an enableLowResourcesMode option to build and watch, which will consume less memory at the cost of slower builds. This is intended for use in resource constrained environments such as Travis.
  • Add createBuildActions. After finding a list of Builders to run, and defining which packages need them applied, use this tool to apply them in the correct order across the package graph.

Deprecations

  • Deprecate PackageGraph.orderedPackages and PackageGraph.dependentsOf.

Internal Improvements

  • Outputs will no longer be rebuilt unless their inputs actually changed, previously if any transtive dependency changed they would be invalidated.
  • Switched to using semantic analyzer summaries, this combined with the better input validation means that, ddc/summary builds are much faster on non-api affecting edits (dependent modules will no longer be rebuilt).
  • Build script invalidation is now much faster, which speeds up all builds.

Bug Fixes

  • The build actions are now checked against the previous builds actions, and if they do not match then a full build is performed. Previously the behavior in this case was undefined.
  • Fixed an issue where once an edge between an output and an input was created it was never removed, causing extra builds to happen that weren't necessary.
  • Build actions are now checked for overlapping outputs in non-checked mode, previously this was only an assert.
  • Fixed an issue where nodes could get in an inconsistent state for short periods of time, leading to various errors.
  • Fixed an issue on windows where incremental builds didn't work.

0.6.0+1

Internal Improvements

  • Now using package:pool to limit the number of open file handles.

Bug fixes

  • Fixed an issue where the asset graph could get in an invalid state if you aren't setting writeToCache: true.

0.6.0

New features

  • Added orderedPackages and dependentsOf utilities to PackageGraph.
  • Added the noPubspec constructor to PackageNode.
  • Added the PackageBuilder and PackageBuildAction classes. These builders only run once per package, and have no primary input. Outputs must be well known ahead of time and are declared with the Iterable<String> get outputs field, which returns relative paths under the current package.
  • Added the isOptional field to BuildAction. Setting this to true means that the action will not run unless some other non-optional action tries to read one of the outputs of the action.
  • Breaking: PackageNode.location has become PackageNode.path, and is now a String (absolute path) instead of a Uri; this prevents needing conversions to/from Uri across the package.
  • Breaking: RunnerAssetReader interface requires you to implement MultiPackageAssetReader and DigestAssetReader. This means the packageName named argument has changed to package, and you have to add the Future<Digest> digest(AssetId id) method. While technically breaking most users do not rely on this interface explicitly.
    • You also no longer have to implement the Future<DateTime> lastModified(AssetId id) method, as it has been replaced with the DigestAssetReader interface.
  • Breaking: ServeHandler.handle has been replaced with Handler ServeHandler.handleFor(String rootDir). This allows you to create separate handlers per directory you want to serve, which maintains pub serve conventions and allows interoperation with pub run test --pub-serve=$PORT.

Bug fixes

  • Breaking: All AssetReader#findAssets implementations now return a Stream<AssetId> to match the latest build package. This should not affect most users unless you are extending the built in AssetReaders or using them in a custom way.
  • Fixed an issue where findAssets could return declared outputs from previous phases that did not actually output the asset.
  • Fixed two issues with writeToCache:
    • Over-declared outputs will no longer attempt to build on each startup.
    • Unrecognized files in the cache dir will no longer be treated as inputs.
  • Asset invalidation has changed from using last modified timestamps to content hashes. This is generally much more reliable, and unblocks other desired features.

Internal changes

  • Added PackageGraphWatcher and PackageNodeWatcher as a wrapper API, including an AssetChange class that is now consistently used across the package.

0.5.0

  • Breaking: Removed buildType field from BuildResult.
  • Breaking: watch now returns a ServeHandler instead of a Stream<BuildResult>. Use ServeHandler.buildResults to get back to the original stream.
  • Breaking: serve has been removed. Instead use watch and use the resulting ServeHandler.handle method along with a server created in the client script to start a server.
  • Prevent reads into .dart_tool for more hermetic builds.
  • Bug Fix: Rebuild entire asset graph if the build script changes.
  • Add writeToCache argument to build and watch which separates generated files from the source directory and allows running builders against other packages.
  • Allow the latest version of package:shelf.

0.4.0+3

  • Bug fix: Don't try to delete files generated for other packages.

0.4.0+2

  • Bug fix: Don't crash after a Builder reads a file from another package.

0.4.0+1

  • Depend on build 0.10.x and build_barback 0.4.x

0.4.0

  • Breaking: The PhaseGroup class has been replaced with a List<BuildAction> in build, watch, and serve. The PhaseGroup and Phase classes are removed. If your current build has multiple actions in a single phase which are depending on not seeing the outputs from other actions in the phase you will need to instead set up the InputSets so that the outputs are filtered out.
  • Breaking: The resolvers argument has been removed from build, watch, and serve.
  • Allow package:build v0.10.x

0.3.4+1

  • Support the latest release of build_barback.

0.3.4

  • Support the latest release of analyzer.

0.3.2

  • Support for build 0.9.0

0.3.1+1

  • Bug Fix: Update AssetGraph version so builds can be run without manually deleting old build directory.
  • Bug Fix: Check for unreadable assets in an async method rather than throw synchronously

0.3.1

  • Internal refactoring of RunnerAssetReader.
  • Support for build 0.8.0
  • Add findAssets on AssetReader implementations
  • Limit Asset reads to those which were available at the start of the phase. This might cause some reads which uses to succeed to fail.

0.3.0

Bug Fixes

  • Fixed a race condition bug 175 that could cause invalid output errors.

Breaking Changes

  • RunnerAssetWriter now requires an additional field, onDelete which is a callback that must be called synchronously within delete.

0.2.0

Add support for the new bytes apis in build.

New Features

  • FileBasedAssetReader and FileBasedAssetWriter now support reading/writing as bytes.

Breaking Changes

  • Removed the AssetCache, CachedAssetReader, and CachedAssetWriter. These may come back at a later time if deemed necessary, but for now they just complicate things unnecessarily without proven benefits.
  • BuildResult#outputs now has a type of List<AssetId> instead of List<Asset>, since the Asset class no longer exists. Additionally this was wasting memory by keeping all output contents around when it's not generally a very useful thing outside of tests (which retain this information in other ways).

0.0.1

  • Initial separate release - split off from build package.

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  build_runner: "^0.7.7+1"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:build_runner/build_runner.dart';
        
Version Uploaded Documentation Archive
0.7.7+1 Jan 19, 2018 Go to the documentation of build_runner 0.7.7+1 Download build_runner 0.7.7+1 archive
0.7.7 Jan 19, 2018 Go to the documentation of build_runner 0.7.7 Download build_runner 0.7.7 archive
0.7.6 Jan 18, 2018 Go to the documentation of build_runner 0.7.6 Download build_runner 0.7.6 archive
0.7.5+1 Jan 10, 2018 Go to the documentation of build_runner 0.7.5+1 Download build_runner 0.7.5+1 archive
0.7.5 Jan 9, 2018 Go to the documentation of build_runner 0.7.5 Download build_runner 0.7.5 archive
0.7.4 Jan 4, 2018 Go to the documentation of build_runner 0.7.4 Download build_runner 0.7.4 archive
0.7.3 Jan 2, 2018 Go to the documentation of build_runner 0.7.3 Download build_runner 0.7.3 archive
0.7.2 Jan 2, 2018 Go to the documentation of build_runner 0.7.2 Download build_runner 0.7.2 archive
0.7.1+1 Dec 24, 2017 Go to the documentation of build_runner 0.7.1+1 Download build_runner 0.7.1+1 archive
0.7.1 Dec 23, 2017 Go to the documentation of build_runner 0.7.1 Download build_runner 0.7.1 archive

All 29 versions...

Analysis

This feature is new.
We welcome feedback.
More details: scoring.

We analyzed this package, and provided a score, details, and suggestions below.

  • completed on Jan 19, 2018
  • Dart: 2.0.0-dev.15.0
  • pana: 0.9.1

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
93 / 100
Health:
Code health derived from static analysis. [more]
100 / 100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100 / 100
Overall score:
Weighted score of the above. [more]
96

Platforms

Detected platforms: server

All libraries have the same platform restriction.

Suggestions

  • The description is too short.

    Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

  • Package is pre-v1 release.

    While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction API.

  • Maintain an example.

    Create a short demo in the example/ directory to show how to use this package. Common file name patterns include: main.dart, example.dart or you could also use build_runner.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev <2.0.0
analyzer >=0.27.1 <0.31.0 0.30.0+4 0.31.0-alpha.2
args >=0.13.7 <2.0.0 1.2.0
async >=1.13.3 <3.0.0 2.0.3
build ^0.12.0 0.12.0
build_barback ^0.5.0 0.5.0+2
build_config ^0.2.1 0.2.2+1
cli_util ^0.1.2 0.1.2+1
code_builder >2.3.0 <4.0.0 3.0.0
collection ^1.14.0 1.14.5
convert ^2.0.1 2.0.1
crypto >=0.9.2 <3.0.0 2.0.2+1
dart_style ^1.0.0 1.0.9
glob ^1.1.0 1.1.5
graphs ^0.1.0 0.1.0
io ^0.3.0 0.3.1
logging ^0.11.2 0.11.3+1
meta ^1.1.0 1.1.2
mime ^0.9.3 0.9.5
path ^1.1.0 1.5.1
pool ^1.0.0 1.3.4
shelf >=0.6.5 <0.8.0 0.7.2
stack_trace ^1.6.0 1.9.1
stream_transform ^0.0.9 0.0.9
watcher ^0.9.7 0.9.7+6
yaml ^2.1.0 2.1.13
Transitive dependencies
barback 0.15.2+14
built_collection 3.0.1
built_value 4.6.1
charcode 1.1.1
code_transformers 0.5.1+3
csslib 0.14.1
fixnum 0.10.6
front_end 0.1.0-alpha.4.1 0.1.0-alpha.7
html 0.13.2+2
http_parser 3.1.1
isolate 1.1.0
kernel 0.3.0-alpha.1.1 0.3.0-alpha.4
matcher 0.12.1+4
package_config 1.0.3
plugin 0.2.0+2
quiver 0.27.0
source_maps 0.10.4
source_span 1.4.0
stream_channel 1.6.3
string_scanner 1.0.2
typed_data 1.1.5
utf 0.9.0+3
Dev dependencies
build_test ^0.10.0
package_resolver ^1.0.2
test ^0.12.0
test_descriptor ^1.0.0