Add --dart-aot-perf and --verbose-durations. (#4394)

Author: davidmorgan

build_runner/CHANGELOG.md

@@ -1,6 +1,11 @@
 ## 2.12.3-wip
 
+- Add `--dart-aot-perf` flag for profiling on Linux. Use it with `--force-aot`.
+  It runs the builders under the `perf` profiling tool which writes to
+  `perf.data`.
+- Add `--verbose-durations` flag that logs durations with greater precision.
 - Improved debugging instructions in README.md.
+- Bug fix: fix line wrapping in `build_runner` args usage output.
 
 ## 2.12.2
 

build_runner/lib/src/bootstrap/bootstrapper.dart

@@ -55,6 +55,7 @@ class Bootstrapper {
   Future<int> run(
     BuiltList<String> arguments, {
     required Iterable<String> jitVmArgs,
+    required bool dartAotPerf,
     Iterable<String>? experiments,
     bool retryCompileFailures = false,
   }) async {
@@ -121,6 +122,7 @@ class Bootstrapper {
                 aotSnapshot: entrypointAotPath,
                 arguments: arguments,
                 message: buildProcessState.serialize(),
+                runUnderPerf: dartAotPerf,
               )
               : await ParentProcess.runAndSend(
                 script: entrypointDillPath,

build_runner/lib/src/bootstrap/processes.dart

@@ -50,15 +50,31 @@ class ParentProcess {
     required String aotSnapshot,
     required Iterable<String> arguments,
     required String message,
+    required bool runUnderPerf,
   }) async {
-    return await _runAndSend(
-      executable: p.join(
-        p.dirname(Platform.resolvedExecutable),
-        'dartaotruntime',
-      ),
-      arguments: [aotSnapshot, ...arguments],
-      message: message,
+    final dartAotRuntime = p.join(
+      p.dirname(Platform.resolvedExecutable),
+      'dartaotruntime',
     );
+    return runUnderPerf
+        ? await _runAndSend(
+          executable: 'perf',
+          arguments: [
+            'record',
+            '-g',
+            '--output',
+            'perf.data',
+            dartAotRuntime,
+            aotSnapshot,
+            ...arguments,
+          ],
+          message: message,
+        )
+        : await _runAndSend(
+          executable: dartAotRuntime,
+          arguments: [aotSnapshot, ...arguments],
+          message: message,
+        );
   }
 
   static Future<RunAndSendResult> _runAndSend({

build_runner/lib/src/build_plan/build_options.dart

@@ -23,13 +23,15 @@ class BuildOptions {
   final String? configKey;
   final BuiltList<String> enableExperiments;
   final bool enableLowResourcesMode;
+  final bool dartAotPerf;
   final bool forceAot;
   final bool forceJit;
   final bool isReleaseBuild;
   final String? logPerformanceDir;
   final bool outputSymlinksOnly;
   final bool trackPerformance;
   final bool verbose;
+  final bool verboseDurations;
   final bool workspace;
 
   late final bool anyMergedOutputDirectory = buildDirs.any(
@@ -41,6 +43,7 @@ class BuildOptions {
     required this.builderConfigOverrides,
     required this.buildFilters,
     required this.configKey,
+    required this.dartAotPerf,
     required this.enableExperiments,
     required this.enableLowResourcesMode,
     required this.forceAot,
@@ -50,6 +53,7 @@ class BuildOptions {
     required this.outputSymlinksOnly,
     required this.trackPerformance,
     required this.verbose,
+    required this.verboseDurations,
     required this.workspace,
   });
 
@@ -59,25 +63,28 @@ class BuildOptions {
   /// command line arg parsing configuration.
   @visibleForTesting
   factory BuildOptions.forTests({
-    bool? forceAot,
-    bool? forceJit,
     BuiltMap<String, BuiltMap<String, Object?>>? builderConfigOverrides,
     BuiltSet<BuildDirectory>? buildDirs,
     BuiltSet<BuildFilter>? buildFilters,
     String? configKey,
+    bool? dartAotPerf,
     BuiltList<String>? enableExperiments,
     bool? enableLowResourcesMode,
+    bool? forceAot,
+    bool? forceJit,
     bool? isReleaseBuild,
     String? logPerformanceDir,
     bool? outputSymlinksOnly,
     bool? trackPerformance,
     bool? verbose,
+    bool? verboseDurations,
     bool? workspace,
   }) => BuildOptions(
     builderConfigOverrides: builderConfigOverrides ?? BuiltMap(),
     buildDirs: buildDirs ?? BuiltSet(),
     buildFilters: buildFilters ?? BuiltSet(),
     configKey: configKey,
+    dartAotPerf: dartAotPerf ?? false,
     enableExperiments: enableExperiments ?? BuiltList(),
     enableLowResourcesMode: enableLowResourcesMode ?? false,
     forceAot: forceAot ?? false,
@@ -87,6 +94,7 @@ class BuildOptions {
     outputSymlinksOnly: outputSymlinksOnly ?? false,
     trackPerformance: trackPerformance ?? false,
     verbose: verbose ?? false,
+    verboseDurations: verboseDurations ?? false,
     workspace: workspace ?? false,
   );
 
@@ -115,6 +123,8 @@ class BuildOptions {
       ),
       buildFilters: _parseBuildFilters(commandLine, rootPackage: rootPackage),
       configKey: commandLine.config,
+      // Only available on Linux.
+      dartAotPerf: commandLine.dartAotPerf ?? false,
       enableExperiments: commandLine.enableExperiments!,
       enableLowResourcesMode: commandLine.lowResourcesMode!,
       forceAot: commandLine.forceAot!,
@@ -125,6 +135,7 @@ class BuildOptions {
       trackPerformance:
           commandLine.trackPerformance! || commandLine.logPerformance != null,
       verbose: commandLine.verbose!,
+      verboseDurations: commandLine.verboseDurations!,
       workspace: commandLine.workspace!,
     );
 
@@ -146,6 +157,7 @@ class BuildOptions {
     builderConfigOverrides: builderConfigOverrides,
     buildFilters: buildFilters ?? this.buildFilters,
     configKey: configKey,
+    dartAotPerf: dartAotPerf,
     enableExperiments: enableExperiments,
     enableLowResourcesMode: enableLowResourcesMode,
     forceAot: forceAot,
@@ -155,6 +167,7 @@ class BuildOptions {
     outputSymlinksOnly: outputSymlinksOnly,
     trackPerformance: trackPerformance,
     verbose: verbose,
+    verboseDurations: verboseDurations,
     workspace: workspace,
   );
 }

build_runner/lib/src/build_runner.dart

@@ -174,6 +174,8 @@ class BuildRunner {
   }) async {
     buildLog.configuration = buildLog.configuration.rebuild((b) {
       b.mode = commandLine.type.buildLogMode;
+      b.verbose = commandLine.verbose;
+      b.verboseDurations = commandLine.verboseDurations;
     });
 
     final bootstrapper = Bootstrapper(
@@ -182,6 +184,7 @@ class BuildRunner {
     );
     return await bootstrapper.run(
       arguments,
+      dartAotPerf: commandLine.dartAotPerf ?? false,
       jitVmArgs: commandLine.jitVmArgs ?? const Iterable.empty(),
       experiments: commandLine.enableExperiments,
       retryCompileFailures:

build_runner/lib/src/build_runner_command_line.dart

@@ -43,21 +43,23 @@ class BuildRunnerCommandLine {
   final BuiltList<String>? buildFilter;
   final String? buildMode;
   final String? config;
+  final bool? dartAotPerf;
   final BuiltList<String>? defines;
   final BuiltList<String>? enableExperiments;
   final bool? forceAot;
   final bool? forceJit;
-  final BuiltList<String>? jitVmArgs;
   final String? hostname;
+  final BuiltList<String>? jitVmArgs;
   final bool? liveReload;
   final String? logPerformance;
   final bool? logRequests;
   final bool? lowResourcesMode;
   final BuiltList<String>? outputs;
   final bool? release;
-  final bool? trackPerformance;
   final bool? symlink;
+  final bool? trackPerformance;
   final bool? verbose;
+  final bool? verboseDurations;
   final bool? workspace;
 
   static Future<BuildRunnerCommandLine?> parse(Iterable<String> arguments) =>
@@ -69,21 +71,23 @@ class BuildRunnerCommandLine {
       buildFilter = argResults.listNamed(buildFilterOption),
       buildMode = argResults.stringNamed(buildModeFlag),
       config = argResults.stringNamed(configOption),
+      dartAotPerf = argResults.boolNamed(dartAotPerfOption),
       defines = argResults.listNamed(defineOption),
       enableExperiments = argResults.listNamed(enableExperimentOption),
       forceAot = argResults.boolNamed(forceAotOption),
       forceJit = argResults.boolNamed(forceJitOption),
-      jitVmArgs = argResults.listNamed(dartJitVmArgOption),
       hostname = argResults.stringNamed(hostnameOption),
+      jitVmArgs = argResults.listNamed(dartJitVmArgOption),
       liveReload = argResults.boolNamed(liveReloadOption),
       logPerformance = argResults.stringNamed(logPerformanceOption),
       logRequests = argResults.boolNamed(logRequestsOption),
       lowResourcesMode = argResults.boolNamed(lowResourcesModeOption),
       outputs = argResults.listNamed(outputOption),
       release = argResults.boolNamed(releaseOption),
-      trackPerformance = argResults.boolNamed(trackPerformanceOption),
       symlink = argResults.boolNamed(symlinkOption),
+      trackPerformance = argResults.boolNamed(trackPerformanceOption),
       verbose = argResults.boolNamed(verboseOption),
+      verboseDurations = argResults.boolNamed(verboseDurationsOption),
       // Only "build" and "watch" support --workspace, default to false for
       // other commands.
       workspace = argResults.boolNamed(workspaceOption) ?? false;
@@ -133,6 +137,7 @@ const deleteFilesByDefaultOption = 'delete-conflicting-outputs';
 const enableExperimentOption = 'enable-experiment';
 const forceAotOption = 'force-aot';
 const forceJitOption = 'force-jit';
+const dartAotPerfOption = 'dart-aot-perf';
 const dartJitVmArgOption = 'dart-jit-vm-arg';
 const hostnameOption = 'hostname';
 const liveReloadOption = 'live-reload';
@@ -141,8 +146,9 @@ const logRequestsOption = 'log-requests';
 const lowResourcesModeOption = 'low-resources-mode';
 const outputOption = 'output';
 const releaseOption = 'release';
-const trackPerformanceOption = 'track-performance';
 const symlinkOption = 'symlink';
+const trackPerformanceOption = 'track-performance';
+const verboseDurationsOption = 'verbose-durations';
 const verboseOption = 'verbose';
 const workspaceOption = 'workspace';
 
@@ -153,10 +159,7 @@ class _CommandRunner extends CommandRunner<BuildRunnerCommandLine> {
     : super(
         'build_runner',
         'Dart build tool.',
-        usageLineLength:
-            buildProcessState.stdio.hasTerminal
-                ? buildProcessState.stdio.terminalColumns
-                : 80,
+        usageLineLength: buildProcessState.stdio.terminalColumns,
       ) {
     addCommand(_build);
     addCommand(_clean);
@@ -170,7 +173,15 @@ class _CommandRunner extends CommandRunner<BuildRunnerCommandLine> {
 
 final _build = _Build();
 
-class _Build extends Command<BuildRunnerCommandLine> {
+/// [Command] with `ArgParser.usageLineLength` set.
+abstract class _Command<T> extends Command<T> {
+  @override
+  final ArgParser argParser = ArgParser(
+    usageLineLength: buildProcessState.stdio.terminalColumns,
+  );
+}
+
+class _Build extends _Command<BuildRunnerCommandLine> {
   _Build() {
     addBuildArgs(argParser, symlinksDefault: false, supportWorkspace: true);
   }
@@ -228,6 +239,11 @@ class _Build extends Command<BuildRunnerCommandLine> {
         negatable: true,
         defaultsTo: false,
       )
+      ..addFlag(
+        verboseDurationsOption,
+        negatable: false,
+        help: 'Logs durations with greater precision.',
+      )
       ..addOption(
         logPerformanceOption,
         help:
@@ -272,7 +288,7 @@ class _Build extends Command<BuildRunnerCommandLine> {
         help:
             'An explicit filter of files to build. Relative paths and '
             '`package:` uris are supported, including glob syntax for paths '
-            'portions (but not package names).\n\n'
+            'portions (but not package names). '
             'If multiple filters are applied then outputs matching any '
             'filter will be built (they do not need to match all filters).',
       )
@@ -284,16 +300,24 @@ class _Build extends Command<BuildRunnerCommandLine> {
         dartJitVmArgOption,
         help:
             'Flags to pass to `dart run` when launching the inner build '
-            'script\n.'
+            'script. '
             'For example, `--dart-jit-vm-arg "--observe" '
             '--dart-jit-vm-arg "--pause-isolates-on-start"` would start the '
             'build script with a debugger attached to it.',
       );
+    if (Platform.isLinux) {
+      argParser.addFlag(
+        dartAotPerfOption,
+        negatable: false,
+        help: 'Run AOT-compiled builders under the `perf` profiling tool.',
+      );
+    }
+
     if (supportWorkspace) {
       argParser.addFlag(
         workspaceOption,
         defaultsTo: false,
-        negatable: true,
+        negatable: false,
         help: 'Build all packages in the current workspace.',
       );
     }
@@ -315,7 +339,7 @@ class _Build extends Command<BuildRunnerCommandLine> {
 
 final _clean = _Clean();
 
-class _Clean extends Command<BuildRunnerCommandLine> {
+class _Clean extends _Command<BuildRunnerCommandLine> {
   @override
   String get name => 'clean';
 
@@ -330,7 +354,7 @@ class _Clean extends Command<BuildRunnerCommandLine> {
 
 final _daemon = _Daemon();
 
-class _Daemon extends Command<BuildRunnerCommandLine> {
+class _Daemon extends _Command<BuildRunnerCommandLine> {
   @override
   String get description => 'Starts the build daemon.';
 
@@ -367,7 +391,7 @@ class _Daemon extends Command<BuildRunnerCommandLine> {
 
 final _run = _Run();
 
-class _Run extends Command<BuildRunnerCommandLine> {
+class _Run extends _Command<BuildRunnerCommandLine> {
   _Run() {
     _Build.addBuildArgs(
       argParser,
@@ -394,7 +418,7 @@ class _Run extends Command<BuildRunnerCommandLine> {
 
 final _serve = _Serve();
 
-class _Serve extends Command<BuildRunnerCommandLine> {
+class _Serve extends _Command<BuildRunnerCommandLine> {
   _Serve() {
     _Build.addBuildArgs(
       argParser,
@@ -438,7 +462,7 @@ class _Serve extends Command<BuildRunnerCommandLine> {
 
 final _test = _Test();
 
-class _Test extends Command<BuildRunnerCommandLine> {
+class _Test extends _Command<BuildRunnerCommandLine> {
   _Test() {
     _Build.addBuildArgs(
       argParser,
@@ -465,7 +489,7 @@ class _Test extends Command<BuildRunnerCommandLine> {
 
 final _watch = _Watch();
 
-class _Watch extends Command<BuildRunnerCommandLine> {
+class _Watch extends _Command<BuildRunnerCommandLine> {
   _Watch() {
     _Build.addBuildArgs(
       argParser,

build_runner/lib/src/commands/build_command.dart

@@ -43,6 +43,7 @@ class BuildCommand implements BuildRunnerCommand {
     buildLog.configuration = buildLog.configuration.rebuild((b) {
       b.mode = BuildLogMode.build;
       b.verbose = buildOptions.verbose;
+      b.verboseDurations = buildOptions.verboseDurations;
       b.onLog = testingOverrides.onLog;
     });