Introduce BuildProcessState, sent to and returned from spawned isolates. (#4024)

Always rebuild if script changed, even if there is an asset graph.

Author: davidmorgan

_test/test/goldens/generated_build_script.dart

@@ -9,8 +9,10 @@ import 'package:build_config/build_config.dart' as _i5;
 import 'package:build_modules/builders.dart' as _i6;
 import 'package:build/build.dart' as _i7;
 import 'dart:isolate' as _i8;
-import 'package:build_runner/build_runner.dart' as _i9;
-import 'dart:io' as _i10;
+import 'package:build_runner/src/build_script_generate/build_process_state.dart'
+    as _i9;
+import 'package:build_runner/build_runner.dart' as _i10;
+import 'dart:io' as _i11;
 
 final _builders = <_i1.BuilderApplication>[
   _i1.apply(
@@ -169,10 +171,11 @@ void main(
   List<String> args, [
   _i8.SendPort? sendPort,
 ]) async {
-  var result = await _i9.run(
+  await _i9.buildProcessState.receive(sendPort);
+  _i9.buildProcessState.isolateExitCode = await _i10.run(
     args,
     _builders,
   );
-  sendPort?.send(result);
-  _i10.exitCode = result;
+  _i11.exitCode = _i9.buildProcessState.isolateExitCode!;
+  await _i9.buildProcessState.send(sendPort);
 }

build_runner/lib/src/build_script_generate/bootstrap.dart

@@ -13,6 +13,7 @@ import 'package:logging/logging.dart';
 import 'package:path/path.dart' as p;
 import 'package:stack_trace/stack_trace.dart';
 
+import 'build_process_state.dart';
 import 'build_script_generate.dart';
 
 final _logger = Logger('Bootstrap');
@@ -39,9 +40,8 @@ Future<int> generateAndRun(
   logger ??= _logger;
   ReceivePort? exitPort;
   ReceivePort? errorPort;
-  ReceivePort? messagePort;
+  RawReceivePort? messagePort;
   StreamSubscription? errorListener;
-  int? scriptExitCode;
 
   var tryCount = 0;
   var succeeded = false;
@@ -52,6 +52,7 @@ Future<int> generateAndRun(
     messagePort?.close();
     await errorListener?.cancel();
 
+    var buildScriptChanged = false;
     try {
       var buildScript = File(scriptLocation);
       var oldContents = '';
@@ -61,6 +62,7 @@ Future<int> generateAndRun(
       var newContents = await generateBuildScript();
       // Only trigger a build script update if necessary.
       if (newContents != oldContents) {
+        buildScriptChanged = true;
         buildScript
           ..createSync(recursive: true)
           ..writeAsStringSync(newContents);
@@ -69,19 +71,27 @@ Future<int> generateAndRun(
       return ExitCode.config.code;
     }
 
-    scriptExitCode = await _createKernelIfNeeded(logger, experiments);
-    if (scriptExitCode != 0) return scriptExitCode!;
+    if (!await _createKernelIfNeeded(
+      logger,
+      experiments,
+      buildScriptChanged: buildScriptChanged,
+    )) {
+      return buildProcessState.isolateExitCode = ExitCode.config.code;
+    }
 
     exitPort = ReceivePort();
     errorPort = ReceivePort();
-    messagePort = ReceivePort();
+    messagePort = RawReceivePort();
     errorListener = errorPort.listen((e) {
       e = e as List<Object?>;
       final error = e[0] ?? TypeError();
       final trace = Trace.parse(e[1] as String? ?? '').terse;
 
       handleUncaughtError(error, trace);
-      if (scriptExitCode == 0) scriptExitCode = 1;
+      if (buildProcessState.isolateExitCode == null ||
+          buildProcessState.isolateExitCode == 0) {
+        buildProcessState.isolateExitCode = 1;
+      }
     });
     try {
       await Isolate.spawnUri(
@@ -113,56 +123,64 @@ Future<int> generateAndRun(
     }
   }
 
-  StreamSubscription? exitCodeListener;
-  exitCodeListener = messagePort!.listen((isolateExitCode) {
-    if (isolateExitCode is int) {
-      scriptExitCode = isolateExitCode;
-    } else {
-      throw StateError(
-        'Bad response from isolate, expected an exit code but got '
-        '$isolateExitCode',
-      );
-    }
-    exitCodeListener!.cancel();
-    exitCodeListener = null;
-  });
+  final sendPortCompleter = Completer<SendPort>();
+  messagePort!.handler = (Object? message) {
+    sendPortCompleter.complete(message as SendPort);
+  };
+  final sendPort = await sendPortCompleter.future;
+
+  await buildProcessState.send(sendPort);
+  buildProcessState.isolateExitCode = null;
+  final buildProcessStateListener = buildProcessState.listen(
+    ReceivePort.fromRawReceivePort(messagePort),
+  );
+
   await exitPort?.first;
   await errorListener?.cancel();
-  await exitCodeListener?.cancel();
+  await buildProcessStateListener.cancel();
+
+  // Can be null if the isolate did not set any exit code.
+  buildProcessState.isolateExitCode ??= 1;
 
-  return scriptExitCode ?? 1;
+  return buildProcessState.isolateExitCode!;
 }
 
 /// Creates a precompiled Kernel snapshot for the build script if necessary.
 ///
 /// A snapshot is generated if:
 ///
+/// - [buildScriptChanged] is `true`
 /// - It doesn't exist currently
 /// - Either build_runner or build_daemon point at a different location than
 ///   they used to, see https://github.com/dart-lang/build/issues/1929.
 ///
-/// Returns zero for success or a number for failure which should be set to the
-/// exit code.
-Future<int> _createKernelIfNeeded(
+/// Returns `true` on success or `false` on failure.
+Future<bool> _createKernelIfNeeded(
   Logger logger,
-  List<String> experiments,
-) async {
+  List<String> experiments, {
+  bool buildScriptChanged = false,
+}) async {
   var assetGraphFile = File(assetGraphPathFor(scriptKernelLocation));
   var kernelFile = File(scriptKernelLocation);
   var kernelCacheFile = File(scriptKernelCachedLocation);
 
   if (await kernelFile.exists()) {
-    // If we failed to serialize an asset graph for the snapshot, then we don't
-    // want to re-use it because we can't check if it is up to date.
-    if (!await assetGraphFile.exists()) {
+    if (buildScriptChanged) {
+      await kernelFile.rename(scriptKernelCachedLocation);
+      logger.warning(
+        'Invalidated precompiled build script because script changed.',
+      );
+    } else if (!await assetGraphFile.exists()) {
+      // If we failed to serialize an asset graph for the snapshot, then we
+      // don't want to re-use it because we can't check if it is up to date.
       await kernelFile.rename(scriptKernelCachedLocation);
       logger.warning(
         'Invalidated precompiled build script due to missing asset graph.',
       );
     } else if (!await _checkImportantPackageDepsAndExperiments(experiments)) {
       await kernelFile.rename(scriptKernelCachedLocation);
       logger.warning(
-        'Invalidated precompiled build script due to core package update',
+        'Invalidated precompiled build script due to core package update.',
       );
     }
   }
@@ -223,12 +241,12 @@ Future<int> _createKernelIfNeeded(
 Failed to precompile build script $scriptLocation.
 This is likely caused by a misconfigured builder definition.
 ''');
-      return ExitCode.config.code;
+      return false;
     }
     // Create _previousLocationsFile.
     await _checkImportantPackageDepsAndExperiments(experiments);
   }
-  return 0;
+  return true;
 }
 
 const _importantPackages = ['build_daemon', 'build_runner'];

build_runner/lib/src/build_script_generate/build_process_state.dart

@@ -0,0 +1,57 @@
+// 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 'dart:async';
+import 'dart:isolate';
+
+/// State for the whole build process.
+///
+/// It's passed from the entrypoint to the spawned build script isolate, then
+/// updated in the host when the isolate exits.
+final BuildProcessState buildProcessState = BuildProcessState({});
+
+extension type BuildProcessState(Map<String, Object?> state) {
+  /// The exit code of the most recent build script isolate, or `null` if there
+  /// was none or it is currently running.
+  int? get isolateExitCode => state['isolateExitCode'] as int?;
+  set isolateExitCode(int? value) => state['isolateExitCode'] = value;
+
+  /// Sends `this` to [sendPort].
+  Future<void> send(SendPort? sendPort) async {
+    sendPort?.send(state);
+  }
+
+  /// Receives `this` from [sendPort], by sending a `SendPort` then listening
+  /// on its corresponding `ReceivePort`.
+  Future<void> receive(SendPort? sendPort) async {
+    if (sendPort == null) {
+      state.clear();
+      return;
+    }
+    final receivePort = ReceivePort();
+    sendPort.send(receivePort.sendPort);
+    final received = await receivePort.first;
+    state
+      ..clear()
+      ..addAll(received as Map<String, Object?>);
+  }
+
+  /// Receives `this` from [receivePort].
+  StreamSubscription<void> listen(ReceivePort receivePort) {
+    StreamSubscription<void>? result;
+    result = receivePort.listen((isolateState) {
+      if (isolateState is Map<String, Object?>) {
+        state
+          ..clear()
+          ..addAll(isolateState);
+      } else {
+        throw StateError(
+          'Bad response from isolate, expected Map but got $isolateState',
+        );
+      }
+      result!.cancel();
+    });
+    return result;
+  }
+}

build_runner/lib/src/build_script_generate/build_script_generate.dart

@@ -227,19 +227,28 @@ Method _main() => Method((b) {
       });
     }),
   );
+  final isolateExitCode = refer(
+    'buildProcessState.isolateExitCode',
+    'package:build_runner/src/build_script_generate/build_process_state.dart',
+  );
   b.body = Block.of([
-    declareVar('result')
+    refer(
+      'buildProcessState.receive',
+      'package:build_runner/src/build_script_generate/build_process_state.dart',
+    ).call([refer('sendPort')]).awaited.statement,
+    isolateExitCode
         .assign(
           refer(
             'run',
             'package:build_runner/build_runner.dart',
           ).call([refer('args'), refer('_builders')]).awaited,
         )
         .statement,
+    refer('exitCode', 'dart:io').assign(isolateExitCode).nullChecked.statement,
     refer(
-      'sendPort',
-    ).nullSafeProperty('send').call([refer('result')]).statement,
-    refer('exitCode', 'dart:io').assign(refer('result')).statement,
+      'buildProcessState.send',
+      'package:build_runner/src/build_script_generate/build_process_state.dart',
+    ).call([refer('sendPort')]).awaited.statement,
   ]);
 });