The build package is a platform-agnostic framework for Dart code or asset generation that works with various build systems (like Bazel or build_runner).

source_gen is a high-level API built on top of build. It provides developer-friendly abstractions for common Dart-specific tasks, such as wrapping Generator instances into PartBuilder or LibraryBuilder to simplify the creation of part of or standalone library files.

To execute builders that consume source_gen, use the build_runner package. First, ensure all dependencies are fetched, then run the build command.

1. Fetch dependencies:

dart pub get

2. Run the build process:

dart run build_runner build

$ dart pub get
$ dart run build_runner build

To use source_gen in your project, add it to your pubspec.yaml. If you are only using it for code generation within your own project and do not intend to publish your generator for others, add it as a dev_dependency.

dependencies:
  source_gen:

Or as a dev_dependency if not publishing the generator

dev_dependencies:
  source_gen:

By default, generated files are placed next to their input files. You can change this by setting the build_extensions option in your build.yaml. This option takes a map where the key is a pattern matching the input and the value is the desired output path. Use {{}} as a placeholder for the filename.

Note: If you move the output directory, you must also update the part statement in the original source file to point to the new location.

targets:
  $default:
    builders:
      # A SharedPartBuilder which uses the combining builder
      source_gen:combining_builder:
        options:
          build_extensions:
            '^lib/{{}}.dart': 'lib/generated/{{}}.g.dart'

      # A PartBuilder or LibraryBuilder
      some_cool_builder:
        options:
          build_extensions:
            '^lib/models/{{}}.dart': 'lib/models/generated/{{}}.foo.dart'

To create a generator, extend either the Generator or GeneratorForAnnotation class.

• Use Generator to generate code for an entire Dart library.
• Use GeneratorForAnnotation to generate code for specific elements within a library that are tagged with a specific annotation.

The CombiningBuilder is a specialized Builder designed to work in a multi-step pipeline.

1. Input: It looks for files matching the pattern [original_file].*[part_id].g.part.
2. Merging: It collects the content of all matching part files, optionally prefixing each with its filename if include_part_name is enabled.
3. Validation: It ensures the input library contains the correct part directive for the intended output file.
4. Output: It produces a single file (typically .g.dart) that contains a part of '...' statement followed by the concatenated contents of all part files, including configured headers, preambles, and ignore directives.

When using SharedPartBuilder, you must configure it to write to the cache and apply the combining_builder to ensure the .g.part files are correctly merged into the final .g.dart file in the source directory.

Note that the build_extensions for a SharedPartBuilder should map .dart inputs to .some_cool_builder.g.part outputs.

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"]

To create a custom code generator, extend the Generator class and override the generate method. The generate method receives a LibraryReader (to inspect the source code elements) and a BuildStep (to interact with the build system).

In this example, MemberCountLibraryGenerator uses the LibraryReader to count top-level variables and returns a string of Dart code that defines a constant with that count.

import 'package:build/build.dart';
import 'package:source_gen/source_gen.dart';

class MemberCountLibraryGenerator extends Generator {
  @override
  String generate(LibraryReader library, BuildStep buildStep) {
    // library is used to inspect the source elements
    final topLevelVarCount = topLevelNumVariables(library).length;

    return '''
// Source library: ${library.element.uri}
const topLevelNumVarCount = $topLevelVarCount;
''';
  }
}