Add option to skip based on primary input content.

Author: davidmorgan

build/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 3.0.1-wip
+
+- Use `build_runner 2.7.0`.
+
 ## 3.0.0
 
 - Removed unused deps: `meta`, `pool`.

build/pubspec.yaml

@@ -1,5 +1,5 @@
 name: build
-version: 3.0.0
+version: 3.0.1-wip
 description: A package for authoring build_runner compatible code generators.
 repository: https://github.com/dart-lang/build/tree/master/build
 resolution: workspace
@@ -10,7 +10,7 @@ environment:
 dependencies:
   analyzer: '>=7.4.0 <8.0.0'
   async: ^2.5.0
-  build_runner_core: '9.2.0'
+  build_runner_core: '9.3.0-wip'
   built_collection: ^5.1.1
   built_value: ^8.9.5
   convert: ^3.0.0

build_config/CHANGELOG.md

@@ -1,5 +1,8 @@
-## 1.1.3-wip
+## 1.2.0-wip
 
+- Add top level key `triggers`. See
+  [the docs](https://github.com/dart-lang/build/blob/master/build_config/README.md#triggers)
+  for more information.
 - Bump the min sdk to 3.7.0.
 - Remove unused dep: `yaml`.
 

build_config/README.md

@@ -232,6 +232,61 @@ these options should be used rarely.
   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:
+
+```yaml
+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:
+
+```yaml
+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`:
+
+```yaml
+triggers:
+  my_package:my_builder:
+    - import my_package/my_builder_annotation.dart
+```
+
+An `import` triggers says that the builder only runs if there is a direct import
+of the specified library. Usually, this will be a library that defines the
+annotation that configures the generator.
+
+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:
+
+```yaml
+triggers:
+  my_package:my_builder:
+    - import third_party_package/annotations.dart
+```
+
 # Publishing `build.yaml` files
 
 `build.yaml` configuration should be published to pub with the package and

build_config/lib/src/build_config.dart

@@ -78,6 +78,13 @@ class BuildConfig {
 
   final List<String> additionalPublicAssets;
 
+  /// Triggers for builders with the option `run_only_if_triggered`.
+  ///
+  /// Keys are builder names, values are not defined here: validity and meaning
+  /// is up to `build_runner`.
+  @JsonKey(name: 'triggers')
+  final Map<String, Object> triggersByBuilder;
+
   /// The default config if you have no `build.yaml` file.
   factory BuildConfig.useDefault(
     String packageName,
@@ -148,6 +155,7 @@ class BuildConfig {
     Map<String, PostProcessBuilderDefinition>? postProcessBuilderDefinitions =
         const {},
     this.additionalPublicAssets = const [],
+    this.triggersByBuilder = const {},
   }) : buildTargets =
            identical(buildTargets, BuildConfig._placeholderBuildTarget)
                ? {

build_config/lib/src/build_config.g.dart

@@ -1,5 +1,5 @@
 name: build_config
-version: 1.1.3-wip
+version: 1.2.0-wip
 description: >-
   Format definition and support for parsing `build.yaml` configuration.
 repository: https://github.com/dart-lang/build/tree/master/build_config

build_config/pubspec.yaml

@@ -1,3 +1,7 @@
+## 3.0.1-wip
+
+- Use `build_runner 2.7.0`.
+
 ## 3.0.0
 
 - Remove unused deps: `graphs`, `logging`, `stream_transform`.

build_resolvers/CHANGELOG.md

@@ -1,5 +1,5 @@
 name: build_resolvers
-version: 3.0.0
+version: 3.0.1-wip
 description: Resolve Dart code in a Builder
 repository: https://github.com/dart-lang/build/tree/master/build_resolvers
 resolution: workspace
@@ -10,8 +10,8 @@ environment:
 dependencies:
   analyzer: '>=7.4.0 <8.0.0'
   async: ^2.5.0
-  build: '3.0.0'
-  build_runner_core: '9.2.0'
+  build: '3.0.1-wip'
+  build_runner_core: '9.3.0-wip'
   collection: ^1.17.0
   convert: ^3.1.1
   crypto: ^3.0.0

build_resolvers/pubspec.yaml

@@ -1,3 +1,11 @@
+## 2.7.0-wip
+
+- Performance: builders can choose to run only when "triggered". A builder runs
+  only if triggered if the option `run_only_if_triggered` is `true`. Triggers
+  are configured in new a top-level section of `build.yaml` called `triggers`.
+  See [the `build_config` docs](https://github.com/dart-lang/build/blob/master/build_config/README.md#triggers)
+  for more information.
+
 ## 2.6.0
 
 - Remove unused deps: `analyzer`, `build_resolvers`, `collection`, `http`,