source_gen
provides utilities for automated source code generation for Dart:
It‘s main purpose is to expose a developer-friendly API on top of lower-level packages like the analyzer or build. You don’t have to use source_gen
in order to generate source code; we also expose a set of library APIs that might be useful in your generators.
Add a dependency on source_gen
in your pubspec.
dependencies: source_gen:
If you‘re only using source_gen
in your own project to generate code and you won’t publish your Generator for others to use, it can be a dev_dependency
:
dev_dependencies: source_gen:
Once you have source_gen
setup, you should reference the examples below.
Extend the Generator
or GeneratorForAnnotation
class and source_gen
will call your generator for a Dart library or for each element within a library tagged with the annotation you are interested in.
source_gen
is based on the build package and exposes options for using your Generator
in a Builder
. Choose a Builder based on where you want the generated code to end up:
.g.dart
files which are referenced as a part
in the original source file, use SharedPartBuilder
. This is the convention for generated code in part files, and this file may also contain code from Generator
s provided by other packages..some_name.dart
files which are referenced as a part
in the original source file, use PartBuilder
. You should choose an extension unique to your package. Multiple Generator
s may output to this file, but they will all come from your package and you will set up the entire list when constructing the builder.import
ed use LibraryBuilder
. Only a single Generator
may be used as a LibraryBuilder
.In order to get the Builder
used with build_runner it must be configured in a build.yaml
file. See build_config for more details. Whenever you are publishing a package that includes a build.yaml
file you should include a dependency on build_config
in your pubspec.
When using SharedPartBuilder
it should always be configured to build_to: cache
(hidden files) and apply the combining_builder
from this package. The combining builder reads in all the pieces written by different shared part builders and writes them to the final .g.dart
output in the user's source directory. You should never use the .g.dart
extension for any other Builder.
builders: some_cool_builder: import: "package:this_package/builder.dart" builder_factories: ["someCoolBuilder"] # The `partId` argument to `SharedPartBuilder` is "some_cool_builder" build_extensions: {".dart": [".some_cool_builder.g.part"]} auto_apply: dependents build_to: cache # To copy the `.g.part` content into `.g.dart` in the source tree applies_builders: ["source_gen|combining_builder"]
combining_builder
ignore_for_file
Sometimes generated code does not support all of the lints specified in the target package. When using a Builder
based on package:source_gen
which applies combining_builder
, set the ignore_for_file
option to a list of lints you wish to be ignored in all generated libraries.
Example build.yaml
configuration:
targets: $default: builders: source_gen|combining_builder: options: ignore_for_file: - lint_alpha - lint_beta
If you provide a builder that uses SharedPartBuilder
and combining_builder
, you should document this feature for your users.
source_gen
and build?Build is a platform-agnostic framework for Dart asset or code generation that is pluggable into build systems including bazel, and standalone tools like build_runner. You could also build your own.
Meanwhile, source_gen
provides an API and tooling that is easily usable on top of build
to make common tasks easier and more developer friendly. For example the PartBuilder
class wraps one or more Generator
instances to make a Builder
which creates part of
files, while the LibraryBuilder
class wraps a single Generator to make a Builder
which creates Dart library files.