Customizing the build behavior of a package is done by creating a build.yaml
file, which describes your configuration.
The full format is described in the docs/build_yaml_format.md file, while this documentation is more focused on specific usage scenarios of the file.
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:
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.'$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
).Builder
s applied to your packageEach 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:
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
.sources
which should have this Builder applied. See sources
configuration above for how to configure this.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
.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.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.Builder
s globallyTarget 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.
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
.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.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.Builder
s to apply to dependents (similar to transformers)If users of your package need to apply some code generation to their package, then you can define Builder
s 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 Builder
s 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:
Builder
class. This should always be a package:
uri.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)
.buildExtensions
maps from each Builder
in builder_factories
.'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.False
."source"
: Outputs go to the source tree next to their primary inputs."cache"
: Outputs go to a hidden build cache 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.builders
section. May contain the following keys:include
and exclude
lists of globs.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.options
when the build is done in dev mode (the default mode).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"
PostProcessBuilder
sPostProcessBuilder
s are configured similarly to normal Builder
s, but they have some different/missing options.
These builders can not be auto-applied on their own, and must always build to cache because their outputs are not declared ahead of time. To apply them a user will need to explicitly enable them on a target, or a Builder
definition can add them to apply_builders
.
Exposed PostProcessBuilder
s 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:
Builder
class. This should always be a package:
uri.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)
.inputExtensions
from the PostProcessBuilder
returned by the builder_factory
.builders
section. May contain the following keys: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"]
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.
.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.build.yaml
filesbuild.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.