Add "triggers" to quickly decide when to not run builders. (#4084)

* Add option to skip based on primary input content.

* Address review comments.

* Address review comments.

Author: davidmorgan

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,81 @@ 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:
+    - annotation MyAnnotation
+    - import my_package/my_builder_annotation.dart
+```
+
+An `annotation` trigger causes the builder to run if an annotation is used.
+So, `- annotation MyAnnotation` is a check for `@MyAnnotation` being used.
+A part file included from a library is also checked for the annotation.
+
+An `import` trigger says that the builder runs if there is a direct import
+of the specified library. This might be useful if a builder can run on code
+without annotations, for example on all classes that `implement` a particular
+type. Then, the import of the type used to trigger generation can be the
+trigger.
+
+Only one trigger has to match for the builder to run; adding more triggers
+can never prevent a builder from running. So, a builder usually only needs
+either an `import` trigger or an `annotation` trigger, not both.
+
+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
+```
+
+Or, if `third_party_package` defines a new constant `NewAnnotation` that can be
+used as an annotation for `my_builder`, it should add a trigger:
+
+```yaml
+triggers:
+  my_package:my_builder:
+    - annotation NewAnnotation
+```
+
 # 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,6 +1,7 @@
 ## 3.0.2-wip
 
 - Use `build` 3.0.2.
+- Use `build_runner` 2.7.0.
 
 ## 3.0.1
 

build_resolvers/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## 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://pub.dev/packages/build_config#triggers)
+  for more information.
 - Remove interactive prompts for whether to delete files.
 - Ignore `-d` flag: always delete files as if `-d` was passed.
 

build_runner/CHANGELOG.md

@@ -16,7 +16,7 @@ dependencies:
   args: ^2.0.0
   async: ^2.5.0
   build: '3.0.2-wip'
-  build_config: ">=1.1.0 <1.2.0"
+  build_config: ">=1.2.0-wip <1.3.0"
   build_daemon: ^4.0.0
   build_runner_core: '9.3.0-wip'
   code_builder: ^4.2.0

build_runner/pubspec.yaml

@@ -1,5 +1,6 @@
 ## 9.3.0-wip
 
+- Add support for build.yaml `triggers`. See `build_runner` 2.7.0 for usage.
 - Remove interactive prompts for whether to delete files.
 - Ignore `-d` flag: always delete files as if `-d` was passed.
 

build_runner_core/CHANGELOG.md

@@ -60,6 +60,10 @@ class AssetGraph implements GeneratedAssetHider {
   final Map<String, Map<PostProcessBuildStepId, Set<AssetId>>>
   _postProcessBuildStepOutputs = {};
 
+  /// Digest of the previous build's `BuildTriggers`, or `null` if this is a
+  /// clean build.
+  Digest? previousBuildTriggersDigest;
+
   /// Digests from the previous build's [BuildPhases], or `null` if this is a
   /// clean build.
   BuiltList<Digest>? previousInBuildPhasesOptionsDigests;