Hacking.

Author: davidmorgan

build_config/lib/src/build_config.dart

@@ -78,6 +78,8 @@ class BuildConfig {
 
   final List<String> additionalPublicAssets;
 
+  final Map<String, Object> triggers;
+
   /// The default config if you have no `build.yaml` file.
   factory BuildConfig.useDefault(
     String packageName,
@@ -148,6 +150,7 @@ class BuildConfig {
     Map<String, PostProcessBuilderDefinition>? postProcessBuilderDefinitions =
         const {},
     this.additionalPublicAssets = const [],
+    this.triggers = const {},
   }) : buildTargets =
            identical(buildTargets, BuildConfig._placeholderBuildTarget)
                ? {

build_config/lib/src/build_config.g.dart

@@ -17,9 +17,12 @@ dependencies:
 dev_dependencies:
   build_runner: ^2.0.0
   # TODO(davidmorgan): add back when released for build 3.0.0.
-  # json_serializable: ^6.0.0
+  json_serializable: ^6.0.0
   term_glyph: ^1.2.0
   test: ^1.16.0
 
 topics:
  - build-runner
+
+dependency_overrides:
+  json_serializable: ^6.0.0

build_config/pubspec.yaml

@@ -486,7 +486,7 @@ class Build {
           readerWriter,
         ),
       )) {
-        buildLog.skipStep(phase: phase, lazy: lazy);
+        buildLog.reuseStep(phase: phase, lazy: lazy);
         return <AssetId>[];
       }
 
@@ -502,20 +502,22 @@ class Build {
       }
 
       var reallyBuild = true;
-      final buildRunnerOptions = phase.builderOptions.config['build_runner'];
-      if (buildRunnerOptions != null) {
-        String? primaryInputSource;
-        final buildIfs = (buildRunnerOptions as Map)['build_if'];
-        if (buildIfs != null) {
-          for (final entry in (buildIfs as Map).entries) {
-            if (entry.key == 'primary_input_contains') {
-              primaryInputSource ??= await readerWriter.readAsString(
-                primaryInput,
-              );
-              if (!primaryInputSource.contains(entry.value as String)) {
-                reallyBuild = false;
-                break;
-              }
+      final runsIfTriggered =
+          phase.builderOptions.config['runs_only_if_triggered'];
+      if (runsIfTriggered == true) {
+        reallyBuild = false;
+        final buildTriggers = options.targetGraph.buildTriggers;
+
+        // TODO(davidmorgan): pull out and digest triggers per build label.
+        final thisBuilderTriggers = buildTriggers.triggers[phase.builderLabel];
+        if (thisBuilderTriggers != null) {
+          final primaryInputSource = await readerWriter.readAsString(
+            primaryInput,
+          );
+          for (final trigger in thisBuilderTriggers) {
+            if (trigger.triggersOnPrimaryInput(primaryInputSource)) {
+              reallyBuild = true;
+              break;
             }
           }
         }
@@ -574,7 +576,7 @@ class Build {
           lazy: lazy,
         );
       } else {
-        buildLog.skipStep(phase: phase, lazy: lazy);
+        buildLog.stepNotTriggered(phase: phase, lazy: lazy);
       }
 
       return readerWriter.assetsWritten;

build_runner_core/lib/src/generate/build.dart

@@ -167,12 +167,7 @@ class BuildOptions {
         requiredRootSourcePaths: [r'$package$', r'lib/$lib$'],
       );
     } on BuildConfigParseException catch (e) {
-      buildLog.error('''
-Failed to parse `build.yaml` for ${e.packageName}.
-
-If you believe you have gotten this message in error, especially if using a new
-feature, you may need to run `dart run build_runner clean` and then rebuild.
-''');
+      buildLog.error(e.toString());
       throw const CannotBuildException();
     }
 

build_runner_core/lib/src/generate/options.dart

@@ -305,8 +305,29 @@ class BuildLog {
     }
   }
 
+  /// Logs that a build step was not triggered.
+  void stepNotTriggered({required InBuildPhase phase, required bool lazy}) {
+    final progress = _getProgress(phase: phase, lazy: lazy);
+    progress.notTriggered++;
+    progress.nextInput = null;
+    final phaseName = phase.name(lazy: lazy);
+    _tick();
+
+    // Usually the next step will immediately run and update with more useful
+    // information, so only display if this is the last for the builder.
+    if (progress.isFinished) {
+      if (_display.displayingBlocks) {
+        _display.block(render());
+      } else {
+        _display.message(Severity.info, _renderPhase(phaseName).toString());
+      }
+    }
+
+    _popPhase();
+  }
+
   /// Logs that a build step has been skipped during an incremental build.
-  void skipStep({required InBuildPhase phase, required bool lazy}) {
+  void reuseStep({required InBuildPhase phase, required bool lazy}) {
     final progress = _getProgress(phase: phase, lazy: lazy);
     progress.skipped++;
     progress.nextInput = null;
@@ -523,6 +544,8 @@ class BuildLog {
       AnsiBuffer.reset,
       if (progress.inputs != 0) ' on ${progress.inputs.renderNamed('input')}',
       if (progress.skipped != 0) '${separator()}${progress.skipped} skipped',
+      if (progress.notTriggered != 0)
+        '${separator()}${progress.notTriggered} not triggered',
       if (progress.builtNew != 0) '${separator()}${progress.builtNew} output',
       if (progress.builtSame != 0) '${separator()}${progress.builtSame} same',
       if (progress.builtNothing != 0)
@@ -583,6 +606,9 @@ class _PhaseProgress {
   /// outputs are up to date.
   int skipped = 0;
 
+  /// Build steps with `run_only_if_triggered` that were not triggered.
+  int notTriggered = 0;
+
   /// Build steps that ran and output new or different output.
   int builtNew = 0;
 
@@ -598,7 +624,8 @@ class _PhaseProgress {
   _PhaseProgress();
 
   /// The number of build steps that have run in this phase.
-  int get runCount => skipped + builtNew + builtSame + builtNothing;
+  int get runCount =>
+      skipped + notTriggered + builtNew + builtSame + builtNothing;
 
   /// Whether this progress in displayed.
   ///

build_runner_core/lib/src/logging/build_log.dart

@@ -6,6 +6,7 @@ import 'dart:async';
 
 import 'package:build/build.dart';
 import 'package:build_config/build_config.dart';
+import 'package:built_collection/built_collection.dart';
 import 'package:graphs/graphs.dart';
 
 import '../generate/build_phases.dart';
@@ -14,6 +15,7 @@ import '../generate/phase.dart';
 import '../logging/build_log.dart';
 import '../logging/build_log_logger.dart';
 import '../validation/config_validation.dart';
+import 'build_triggers.dart';
 import 'package_graph.dart';
 import 'target_graph.dart';
 

build_runner_core/lib/src/package_graph/apply_builders.dart

@@ -0,0 +1,37 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:built_collection/built_collection.dart';
+
+class BuildTriggers {
+  final BuiltMap<String, BuiltSet<BuildTrigger>> triggers;
+
+  BuildTriggers({required this.triggers});
+
+  // TODO(davidmorgan): fix.
+  int get identity => triggers.toString().hashCode;
+}
+
+abstract class BuildTrigger {
+  static BuildTrigger? tryParse(String trigger) {
+    if (trigger.startsWith('import ')) {
+      trigger = trigger.substring('import '.length);
+      return ImportBuildTrigger(trigger);
+    }
+    return null;
+  }
+
+  bool triggersOnPrimaryInput(String source);
+}
+
+class ImportBuildTrigger implements BuildTrigger {
+  final String import;
+
+  ImportBuildTrigger(this.import);
+
+  @override
+  bool triggersOnPrimaryInput(String source) {
+    return source.contains(import);
+  }
+}

build_runner_core/lib/src/package_graph/build_triggers.dart

@@ -6,11 +6,13 @@ import 'dart:async';
 
 import 'package:build/build.dart';
 import 'package:build_config/build_config.dart';
+import 'package:built_collection/built_collection.dart';
 import 'package:glob/glob.dart';
 
 import '../generate/input_matcher.dart';
 import '../generate/options.dart' show defaultNonRootVisibleAssets;
 import '../logging/build_log.dart';
+import 'build_triggers.dart';
 import 'package_graph.dart';
 
 /// Like a [PackageGraph] but packages are further broken down into modules
@@ -36,11 +38,17 @@ class TargetGraph {
   /// The [BuildConfig] of the root package.
   final BuildConfig rootPackageConfig;
 
+  // The [BuildTrigger]s accumulated across all packages.
+  final BuildTriggers buildTriggers;
+
+  /// The [BuildTriggers] accumulated across all packages.
+
   TargetGraph._(
     this.allModules,
     this.modulesByPackage,
     this._publicAssetsByPackage,
     this.rootPackageConfig,
+    this.buildTriggers,
   );
 
   /// Builds a [TargetGraph] from [packageGraph].
@@ -66,10 +74,34 @@ class TargetGraph {
     final publicAssetsByPackage = <String, InputMatcher>{};
     final modulesByPackage = <String, List<TargetNode>>{};
     late BuildConfig rootPackageConfig;
+    final buildTriggers = <String, Set<BuildTrigger>>{};
     for (final package in packageGraph.allPackages.values) {
       final config =
           overrideBuildConfig[package.name] ??
           await _packageBuildConfig(package);
+
+      final packageTriggers = config.triggers;
+      for (final entry in packageTriggers.entries) {
+        final triggerPackage = entry.key;
+        final triggers = entry.value;
+        if (triggers is List<Object?>) {
+          for (final triggerString in triggers) {
+            BuildTrigger? trigger;
+            if (triggerString is String) {
+              trigger = BuildTrigger.tryParse(triggerString);
+            }
+            if (trigger != null) {
+              (buildTriggers[triggerPackage] ??= {}).add(trigger);
+            } else {
+              throw BuildConfigParseException(
+                package.name,
+                'Invalid trigger: `$triggerString`',
+              );
+            }
+          }
+        }
+      }
+
       List<String> defaultInclude;
       if (package.isRoot) {
         defaultInclude = [
@@ -124,6 +156,11 @@ class TargetGraph {
       modulesByPackage,
       publicAssetsByPackage,
       rootPackageConfig,
+      BuildTriggers(
+        triggers: BuiltMap.from(
+          buildTriggers.map((k, v) => MapEntry(k, v.build())),
+        ),
+      ),
     );
   }
 
@@ -229,15 +266,19 @@ Future<BuildConfig> _packageBuildConfig(PackageNode package) async {
     );
   } on ArgumentError // ignore: avoid_catching_errors
   catch (e) {
-    throw BuildConfigParseException(package.name, e);
+    throw BuildConfigParseException(package.name, e.toString());
   }
 }
 
 class BuildConfigParseException implements Exception {
   final String packageName;
-  final dynamic exception;
+  final String message;
 
-  BuildConfigParseException(this.packageName, this.exception);
+  BuildConfigParseException(this.packageName, this.message);
+
+  @override
+  String toString() =>
+      'Failed to parse `build.yaml` for $packageName. $message';
 }
 
 /// Returns the [sources] are not included in any [targets].

build_runner_core/lib/src/package_graph/target_graph.dart

@@ -157,7 +157,7 @@ Building, full build.'''),
         primaryInput: AssetId('pkg', 'lib/l3.dart'),
         lazy: false,
       );
-      buildLog.skipStep(phase: phases.keys.first, lazy: false);
+      buildLog.reuseStep(phase: phases.keys.first, lazy: false);
       expect(
         render(),
         padLinesRight('''