build 4.0.0

A package for authoring build_runner compatible code generators.

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

Package for writing code generators, called builders, that run with build_runner.

• See also: source_gen
• The Builder interface
  • Using the analyzer
• Examples

See also: source_gen

The source_gen package provides helpers for writing common types of builder, for example builders that are triggered by a particular annotation.

Most builders should use source_gen, but it's still useful to learn about the underlying Builder interface that source_gen plugs into.

The Builder interface

A builder implements the Builder interface.

abstract class Builder {
  /// Declares inputs and outputs by extension.
  Map<String, List<String>> get buildExtensions;

  /// Builds all outputs for a single input.
  FutureOr<void> build(BuildStep buildStep);
}

Its buildExtensions getter declares what inputs it runs on and what outputs it might produce.

During a build its build method gets called once per matching input.

It uses buildStep to read, analyze and write files.

For example, here is a builder that copies input .txt files to .txt.copy files:

class CopyBuilder implements Builder {
  @override
  final buildExtensions = const {
    '.txt': ['.txt.copy']
  };

  @override
  Future<void> build(BuildStep buildStep) async {
    // Create the output ID from the build step input ID.
    final inputId = buildStep.inputId;
    final outputId = inputId.addExtension('.copy');

    // Read from the input, write to the output.
    final contents = await buildStep.readAsString(inputId);
    await buildStep.writeAsString(outputId, contents);
  }
}

Outputs are optional. For example, a builder that is activated by a particular annotation will output nothing if it does not find that annotation.

Using the analyzer

The buildStep passed to build gives easy access to the analyzer for processing Dart source code.

Use buildStep.resolver.compilationUnitFor to parse a single source file, or libraryFor to fully resolve it. This can be used to introspect the full API of the source code the builder is running on. For example, a builder can learn enough about a class's field and field types to correctly serialize it.

Examples

There are some simple examples in the build repo.

For real examples of builders, see the list of popular builders in the build_runner package documentation.