build_config

Questions? Suggestions? Found a bug? Please file an issue or start a discussion.

Configuration file format for build_runner builds.

• See also: build_yaml_format.md
• Dividing a package into build targets
• Configuring builders applied to your package
• Configuring builders globally
• Defining builders to apply to depenents
• Defining post process builders
• Adjusting builder ordering
• Triggers
• Publishing build.yaml files
• FAQ
  • How do I avoid running builders on unnecessary inputs?
  • How is the configuration for a builder resolved?
  • How can I include additional sources in my build?

See also: build_yaml_format.md

See also docs/build_yaml_format.md for a more technical description of the format.

Dividing a package into build targets

When a Builder should be applied to a subset of files in a package the package can be broken up into multiple 'targets'. Targets are configured in the targets section of the build.yaml. The key for each target makes up the name for that target. Targets can be referred to in '$definingPackageName:$targetname'. When the target name matches the package name it can also be referred to as just the package name. One target in every package must use the package name so that consumers will use it by default. In the build.yaml file this target can be defined with the key $default or with the name of the package.

Each target may also contain the following keys:

• sources: List of Strings or Map, Optional. The set of files within the package which make up this target. Files are specified using glob syntax. If a List of Strings is used they are considered the 'include' globs. If a Map is used can only have the keys include and exclude. Any file which matches any glob in include and no globs in exclude is considered a source of the target. When include is omitted every file is considered a match.
• dependencies: List of Strings, Optional. The targets that this target depends on. Strings in the format '$packageName:$targetName' to depend on a target within a package or $packageName to depend on a package's default target. By default this is all of the package names this package depends on (from the pubspec.yaml).
• builders: Map, Optional. See "configuring builders" below.

Configuring builders applied to your package

Each target can specify a builders key which configures the builders which are applied to that target. The value is a Map from builder to configuration for that builder. The key is in the format '$packageName:$builderName'. The configuration may have the following keys:

• enabled: Boolean, Optional: Whether to apply the builder to this target. Omit this key if you want the default behavior based on the builder's auto_apply configuration. Builders which are manually applied (auto_apply: none) are only ever used when there is a target specifying the builder with enabled: True.
• generate_for: List of String or Map, Optional:. The subset of files within the target's sources which should have this Builder applied. See sources configuration above for how to configure this.
• options: Map, Optional: A free-form map which will be passed to the Builder as a BuilderOptions when it is constructed. Usage varies depending on the particular builder. Values in this map will override the default provided by builder authors. Values may also be overridden based on the build mode with dev_options or release_options.
• dev_options: Map, Optional: A free-form map which will be passed to the Builder as a BuilderOptions when it is constructed. Usage varies depending on the particular builder. The values in this map override Builder defaults or non mode-specific options per-key when the build is done in dev mode.
• release_options: Map, Optional: A free-form map which will be passed to the Builder as a BuilderOptions when it is constructed. Usage varies depending on the particular builder. The values in this map override Builder defaults or non mode-specific options when the build is done in release mode.

Configuring builders globally

Target level builder options can be overridden globally across all packages with the global_options section. These options are applied after all Builder defaults and target level configuration, and before --define command line arguments.

• options: Map, Optional: A free-form map which will be passed to the Builder as a BuilderOptions when it is constructed. Usage varies depending on the particular builder. Values in this map will override the default provided by builder authors or at the target level. Values may also be overridden based on the build mode with dev_options or release_options.
• dev_options: Map, Optional: A free-form map which will be passed to the Builder as a BuilderOptions when it is constructed. Usage varies depending on the particular builder. The values in this map override all other values per-key when the build is done in dev mode.
• release_options: Map, Optional: A free-form map which will be passed to the Builder as a BuilderOptions when it is constructed. Usage varies depending on the particular builder. The values in this map override all other values per-key when the build is done in release mode.

Defining builders to apply to dependents

If users of your package need to apply some code generation to their package, then you can define Builders and have those applied to packages with a dependency on yours.

The key for a Builder will be normalized so that consumers of the builder can refer to it in '$definingPackageName:$builderName' format. If the builder name matches the package name it can also be referred to with just the package name.

Exposed Builders are configured in the builders section of the build.yaml. This is a map of builder names to configuration. Each builder config may contain the following keys:

• import: Required. The import uri that should be used to import the library containing the Builder class. This should always be a package: uri.
• builder_factories: A List<String> which contains the names of the top-level methods in the imported library which are a function fitting the typedef Builder factoryName(BuilderOptions options).
• build_extensions: Required. A map from input extension to the list of output extensions that may be created for that input. This must match the merged buildExtensions maps from each Builder in builder_factories.
• auto_apply: Optional. The packages which should have this builder automatically to applied. Defaults to 'none' The possibilities are:
  • "none": Never apply this Builder unless it is manually configured
  • "dependents": Apply this Builder to the package with a direct dependency on the package exposing the builder.
  • "all_packages": Apply this Builder to all packages in the transitive dependency graph.
  • "root_package": Apply this Builder only to the top-level package.
• required_inputs: Optional, see adjusting builder ordering
• runs_before: Optional, see adjusting builder ordering
• applies_builders: Optional, list of Builder keys. Specifies that other builders should be run on any target which will run this Builder.
• is_optional: Optional, boolean. Specifies whether a Builder can be run lazily, such that it won't execute until one of it's outputs is requested by a later Builder. This option should be rare. Defaults to False.
• build_to: Optional. The location that generated assets should be output to. The possibilities are:
  • "source": Outputs are written at their package paths. They're written next to their primary inputs except for the unusual case when build_extensions is used to match and change the enclosing path.
  • "cache": Outputs are written in the artifact tree under .dart_tool/build/generated and won't be published. The default is "cache". If a Builder specifies that it outputs to "source" it will never run on any package other than the root - but does not necessarily need to use the "root_package" value for "auto_apply". If it would otherwise run on a non-root package it will be filtered out.
• defaults: Optional: Default values to apply when a user does not specify the corresponding key in their builders section. May contain the following keys:
  • generate_for: A list of globs that this Builder should run on as a subset of the corresponding target, or a map with include and exclude lists of globs.
  • options: Arbitrary yaml map, provided as the config map in BuilderOptions to the BuilderFactory for this builder. Individual keys will be overridden by configuration provided in either dev_options or release_options based on the build mode, and then overridden by any user specified configuration.
  • dev_options: Arbitrary yaml map. Values will replace the defaults from options when the build is done in dev mode (the default mode).
  • release_options: Arbitrary yaml map. Values will replace the defaults from options when the build is done in release mode (with --release).

Example builders config:

builders:
                  my_builder:
                    import: "package:my_package/builder.dart"
                    builder_factories: ["myBuilder"]
                    build_extensions: {".dart": [".my_package.dart"]}
                    auto_apply: dependents
                    defaults:
                      release_options:
                        some_key: "Some value the users will want in release mode"
                

Defining post process builders

PostProcessBuilders are configured similarly to normal Builders, but they have some different/missing options.

These builders can't be auto-applied. They are applied when explicitly applied to a target and when a Builder definition applies them using apply_builders.

Exposed PostProcessBuilders are configured in the post_process_builders section of the build.yaml. This is a map of builder names to configuration. Each post process builder config may contain the following keys:

• import: Required. The import uri that should be used to import the library containing the Builder class. This should always be a package: uri.
• builder_factory: A String which contains the name of the top-level method in the imported library which is a function fitting the typedef PostProcessBuilder factoryName(BuilderOptions options).
• input_extensions: Required. A list of input extensions that will be processed. This must match the inputExtensions from the PostProcessBuilder returned by the builder_factory.
• build_to: Optional. The location that generated assets should be output to. The possibilities are:
  • "source": Outputs are written at their package paths.
  • "cache": Outputs are written in the artifact tree under .dart_tool/build/generated and won't be published.
• defaults: Optional: Default values to apply when a user does not specify the corresponding key in their builders section. May contain the following keys:
  • generate_for: A list of globs that this Builder should run on as a subset of the corresponding target, or a map with include and exclude lists of globs.

Example config with a normal builder which auto-applies a post_process_builder:

builders:
                  # The regular builder config, creates `.tar.gz` files.
                  regular_builder:
                    import: "package:my_package/builder.dart"
                    builder_factories: ["myBuilder"]
                    build_extensions: {".dart": [".tar.gz"]}
                    auto_apply: dependents
                    apply_builders: [":archive_extract_builder"]
                post_process_builders:
                  # The post process builder config, extracts `.tar.gz` files.
                  extract_archive_builder:
                    import: "package:my_package/extract_archive_builder.dart"
                    builder_factory: "myExtractArchiveBuilder"
                    input_extensions: [".tar.gz"]
                

Adjusting builder ordering

Both required_inputs and runs_before can be used to tweak the order that Builders run in on a given target. These work by indicating a given builder is a dependency of another. The resulting dependency graph must not have cycles and these options should be used rarely.

• required_inputs: Optional, list of extensions, defaults to empty list. If a Builder must see every input with one or more file extensions they can be specified here and it will be guaranteed to run after any Builder which might produce an output of that type. For instance a compiler must run after any Builder which can produce .dart outputs or those libraries can't be compiled. A Builder may not specify that it requires an output that it also produces since this would be a self-cycle.
• runs_before: Optional, list of Builder keys. If a Builder is producing outputs which are intended to be inputs to other Builders they may be specified here. This guarantees that the specified Builders will be ordered later than this one. This will not cause Builders to be applied if they would not otherwise run, it only affects ordering. If a builder emits files that should always be the input to another specific builder, use both runs_before and applies_builder to configure both ordering and ensure that steps are not skipped.

Triggers

Triggers are a performance heuristic that allow builders to quickly decide not to run.

A builder runs only if triggered if the option run_only_if_triggered is true. This can be enabled for the builder:

builders:
                  my_builder:
                    import: "package:my_package/builder.dart"
                    builder_factories: ["myBuilder"]
                    build_extensions: {".dart": [".my_package.dart"]}
                    defaults:
                      options:
                        run_only_if_triggered: true
                

Or, enabled/disabled in the build.yaml of the package applying the builder:

targets:
                  $default:
                    builders:
                      my_package:my_builder:
                        options:
                          run_only_if_triggered: true # or `false`
                

Triggers are defined in a new top-level section called triggers:

triggers:
                  my_package:my_builder:
                    - annotation MyAnnotation
                    - import my_package/my_builder_annotation.dart
                

An annotation trigger causes the builder to run if an annotation is used. So, - annotation MyAnnotation is a check for @MyAnnotation being used. A part file included from a library is also checked for the annotation.

An import trigger says that the builder runs if there is a direct import of the specified library. This might be useful if a builder can run on code without annotations, for example on all classes that implement a particular type. Then, the import of the type used to trigger generation can be the trigger.

Only one trigger has to match for the builder to run; adding more triggers can never prevent a builder from running. So, a builder usually only needs either an import trigger or an annotation trigger, not both.

Triggers are collected from all packages in the codebase, not just packages defining or applying builders. This allows a package to provide new ways to trigger a builder from an unrelated package. For example, if third_party_package re-exports the annotation in package:my_package/my_builder_annotation.dart then it should also add a trigger:

triggers:
                  my_package:my_builder:
                    - import third_party_package/annotations.dart
                

Or, if third_party_package defines a new constant NewAnnotation that can be used as an annotation for my_builder, it should add a trigger:

triggers:
                  my_package:my_builder:
                    - annotation NewAnnotation
                

Publishing build.yaml files

build.yaml configuration should be published to pub with the package and checked in to source control. Whenever a package is published with a build.yaml it should mark a dependency on build_config to ensure that the package consuming the config has a compatible version. Breaking version changes which do not impact the configuration file format will be clearly marked in the changelog.

FAQ

How do I avoid running builders on unnecessary inputs?

You can skip unnecessary inputs and so speed up your build using the generate_for option of the builder:

targets:
                  $default:
                    builders:
                      # Typically the builder key is just the package name, run
                      # `dart run build_runner doctor` to check your config.
                      <builder-key>:
                        generate_for:
                          # Example glob for only the Dart files under `lib/models`
                          - lib/models/*.dart
                

How is the configuration for a builder resolved?

Builders are constructed with a map of options which is resolved from the builder specified defaults and user overrides. The configuration is specific to a target and build mode. The configuration is "merged" one by one, where the higher precedence configuration overrides values by String key. The order of precedence from lowest to highest is:

• Builder defaults without a mode.
• Builder defaults by mode.
• Target configuration without a mode.
• Target configuration by mode.
• Global options without a mode.
• Global options by mode.
• Options specified on the command line.

For example:

builders:
                  some_builder:
                    # Some required fields omitted
                    defaults:
                      options:
                        some_option: "Priority 0"
                      release_options:
                        some_option: "Priority 1"
                      dev_options:
                        some_option: "Priority 1"
                targets:
                  $default:
                    builders:
                      some_package:some_builder:
                        options:
                          some_option: "Priority 2"
                        release_options:
                          some_option: "Priority 3"
                        dev_options:
                          some_option: "Priority 3"
                
                global_options:
                  some_package:some_builder:
                    options:
                      some_option: "Priority 4"
                    release_options:
                      some_option: "Priority 5"
                    dev_options:
                      some_option: "Priority 5"
                

And when running the build:

dart run build_runner build --define=some_package:some_builder=some_option="Priority 6"
                

If values are valid JSON they are parsed to objects. For example, it's possible to pass lists and maps. If values are not valid JSON they are used as exact strings.

How can I include additional sources in my build?

The build_runner package defaults the included source files to directories derived from the package layout conventions.

If you have additional files which you would like to be included as part of the build, you can do that with the sources field on the $default target:

targets:
                  $default:
                    sources:
                      - my_custom_sources/**
                      - lib/**
                      - web/**
                      # Note that it is important to include these in the default target.
                      - pubspec.*
                      - $package$
                

1.3.3

• Clarify terminology: refer to .dart_tool/build/generated as the "artifact tree", and the normal output location as the "package path".

1.3.2

• Reject builder names with the wrong package name.

1.3.1

• Document that --define values are parsed as JSON with a fallback.
• Require Dart 3.8.0.

1.3.0

• Add build_to key to post_process_builders. Like the builders key, it controls where the builder output is written: by default cache, the hidden build cache, or source to write next to source files.

1.2.0

• Add top level key triggers. See the docs for more information.
• Bump the min sdk to 3.7.0.
• Remove unused dep: yaml.
• Documentation revamp.

1.1.2

• Stop using deprecated JsonKey.ignore.
• Bump the min sdk to 3.6.0.

1.1.1

• Expand pubspec description to improve pub score.

1.1.0

• Require Dart 2.14
• Support runsBefore global configuration for builders. This allows users to have some control over builder ordering.

1.0.0

• Migrate to null safety.

0.4.7

• Allow the latest pubspec_parse and checked_yaml.

0.4.6

• Comment out dev dependency temporarily to break source_gen/json_serializable dependency loop.

0.4.5

• Allow package:json_annotation v4.x.

0.4.4

• Support the latest pkg:yaml.

0.4.3

• Added the additional_public_assets option, which describes the assets readable when the configured package is not the root of the build.

0.4.2

• Add support for an auto_apply_builders option to the target config.
  • Defaults to true (the previous behavior), setting it to false means all builders have to be explicitly enabled.

0.4.1+1

• Support the latest release of package:json_annotation.
• Increased the lower bound for the Dart SDK to >=2.3.0.

0.4.1

• Added optional configYamlPath parameter to BuildConfig.parse. When provided, errors reported when parsing build configuration will include the file path.

0.4.0

• Breaking for build systems - change type of BuilderOptions fields to Map<String, dynamic> to drop dependency on build. Does not impact packages only depending on build.yaml parsing.
• Breaking for build systems - versioning scheme is changing to match package:build. Changes which are breaking to users - those with build.yaml files will be indicated with a breaking major version bump. Changed which are breaking to build system implementors - those who use the Dart API for this package, will be indicated with a minor version bump.

0.3.2

• Add an explicit error when buildExtensions is configured to overwrite it's input.
• Add an explicit error when an InputSet has an empty or null value in a glob list.
• Increase lower bound SDK constraint to 2.0.0.
• Normalize builder keys with the legacy | separator to use : instead.

0.3.1+4

• Support the latest package:json_annotation.

0.3.1+3

• Support package:build version 1.x.x.

0.3.1+2

• Support package:json_annotation v1.

0.3.1+1

• Increased the upper bound for the sdk to <3.0.0.

0.3.1

• Improve validation and errors when parsing build.yaml.
• Add BuildConfig.globalOptions support.

0.3.0

• Parsing of build.yaml files is now done with the json_serializable package and is Dart 2 compatible.

  • The error reporting will be a bit different, but generally should be better, and will include the yaml spans of the problem sections.

Breaking Changes

There are no changes to the build.yaml format, the following changes only affect the imperative apis of this package.

• The Constructors for most of the build config classes other than BuildConfig itself now have to be ran inside a build config zone, which can be done using the runInBuildConfigZone function. This gives the context about what package is currently being parsed, as well as what the default dependencies should be for targets.
• Many constructor signatures have changed, for the most part removing the package parameter (it is now read off the zone).

0.2.6+2

• Restore error for missing default target.

0.2.6+1

• Restore error for missing build extensions.

0.2.6

• The target and build_extensions keys for builder definitions are now optional and should be omitted in most cases since they are currently unused.
• Support options based on mode, add devOptions and releaseOptions on TargetBuilderConfig.
• Support applying default options based on builder definitions, add option, devOptions, and releaseOptions to TargetBuilderConfigDefaults.
• Ensure that defaults and generateFor fields are never null.
• Add InputSet.anything to name the input sets that don't filter out any assets.

0.2.5

• Added post_process_builders section to build.yaml. See README.md for more information.-dev
• Adds support for $default as a dependency, i.e.:

targets:
                  $default:
                    ...
                  foo:
                    dependencies:
                      - $default
                

0.2.4

• Add support for runs_before in BuilderDefinition.

0.2.3

• Expose key normalization methods publicly, these include:
  • normalizeBuilderKeyUsage
  • normalizeTargetKeyUsage

0.2.2+1

• Expand support for package:build to include version 0.12.0.

0.2.2

• Bug fix: Empty build.yaml files no longer fail to parse.
• Allow $default as a target name to get he package name automatically filled in.

0.2.1

• Change the default for BuilderDefinition.buildTo to BuildTo.cache. Builders which want to operate on the source tree will need to explicitly opt in. Allow this regardless of the value of autoApply and the build system will need to filter out the builders that can't run.
• By default including any configuration for a Builder within a BuildTarget will enabled that builder.

0.2.0

• Add build_to option to Builder configuration.
• Add BuildConfig.fromBuildConfigDir for cases where the package name and dependencies are already known.
• Add TargetBuilderConfig class to configure builders applied to specific targets.
• Add TargetBuilderConfigDefaults class for Builder authors to provide default configuration.
• Add InputSet and change sources and generate_for to use it.
• Remove BuildTarget.isDefault and related config parsing. The default will be determined by the target which matches the package name.
• Normalize Target and Builder names so they are scoped to the package they are defined in.

Breaking

• Remove BuildConfigSet class. This was unused.
• Hide Pubspec class. Construct BuildConfig instances with a package path rather than an already created Pubspec instance.

0.1.1

• Add auto_apply option to Builder configuration.
• Add required_inputs option to Builder configuration.
• Add is_optional option to Builder configuration.

0.1.0

• Initial release - pulled from package:dazel. Updated to support build_extensions instead of input_extension and output_extensions.