std.Build: add --seed argument to randomize step dependencies spawning

help detect possibly hidden dependencies on the running order of steps,
especially in -j1 mode

Author: Sahnvour

lib/build_runner.zig

@@ -192,6 +192,12 @@ pub fn main() !void {
                     std.debug.print("Expected argument after {s}\n\n", .{arg});
                     usageAndErr(builder, false, stderr_stream);
                 } };
+            } else if (mem.eql(u8, arg, "--seed")) {
+                const next_arg = nextArg(args, &arg_idx) orelse {
+                    std.debug.print("Expected a string after {s}\n\n", .{arg});
+                    usageAndErr(builder, false, stderr_stream);
+                };
+                builder.seed = next_arg;
             } else if (mem.eql(u8, arg, "--debug-log")) {
                 const next_arg = nextArg(args, &arg_idx) orelse {
                     std.debug.print("Expected argument after {s}\n\n", .{arg});
@@ -369,8 +375,14 @@ fn runStepNames(
     }
 
     const starting_steps = try arena.dupe(*Step, step_stack.keys());
+
+    const useed = std.hash.XxHash64.hash(0x1312, b.seed);
+    var rng = std.rand.DefaultPrng.init(useed);
+    const rand = rng.random();
+    rand.shuffle(*Step, starting_steps);
+
     for (starting_steps) |s| {
-        checkForDependencyLoop(b, s, &step_stack) catch |err| switch (err) {
+        buildAndCheckGraphForDependencyLoop(b, s, &step_stack, rand) catch |err| switch (err) {
             error.DependencyLoopDetected => return error.UncleanExit,
             else => |e| return e,
         };
@@ -485,6 +497,9 @@ fn runStepNames(
         stderr.writeAll("Build Summary:") catch {};
         ttyconf.setColor(stderr, .reset) catch {};
         stderr.writer().print(" {d}/{d} steps succeeded", .{ success_count, total_count }) catch {};
+        ttyconf.setColor(stderr, .dim) catch {};
+        stderr.writer().print(" (seed is {s})", .{b.seed}) catch {};
+        ttyconf.setColor(stderr, .reset) catch {};
         if (skipped_count > 0) stderr.writer().print("; {d} skipped", .{skipped_count}) catch {};
         if (failure_count > 0) stderr.writer().print("; {d} failed", .{failure_count}) catch {};
 
@@ -731,10 +746,22 @@ fn printTreeStep(
     }
 }
 
-fn checkForDependencyLoop(
+/// Traverse the dependency graph depth-first and make it undirected by having
+/// steps know their dependants (they only know dependencies at start).
+/// Along the way, check that there is no dependency loop, and record the steps
+/// in traversal order in `step_stack`.
+/// Each step has its dependencies traversed in random order, this accomplishes
+/// two things:
+/// - `step_stack` will be in randomized-depth-first order, so the build runner
+///   spawns steps in a random (but optimized) order
+/// - each step's `dependants` list is also filled in a random order, so that
+///   when it finishes executing in `workerMakeOneStep`, it spawns next steps
+///   to run in random order
+fn buildAndCheckGraphForDependencyLoop(
     b: *std.Build,
     s: *Step,
     step_stack: *std.AutoArrayHashMapUnmanaged(*Step, void),
+    rand: std.rand.Random,
 ) !void {
     switch (s.state) {
         .precheck_started => {
@@ -745,10 +772,16 @@ fn checkForDependencyLoop(
             s.state = .precheck_started;
 
             try step_stack.ensureUnusedCapacity(b.allocator, s.dependencies.items.len);
-            for (s.dependencies.items) |dep| {
+
+            // We dupe to avoid shuffling the steps in the summary, it depends
+            // on s.dependencies' order.
+            const deps = b.allocator.dupe(*Step, s.dependencies.items) catch @panic("OOM");
+            rand.shuffle(*Step, deps);
+
+            for (deps) |dep| {
                 try step_stack.put(b.allocator, dep, {});
                 try dep.dependants.append(b.allocator, s);
-                checkForDependencyLoop(b, dep, step_stack) catch |err| {
+                buildAndCheckGraphForDependencyLoop(b, dep, step_stack, rand) catch |err| {
                     if (err == error.DependencyLoopDetected) {
                         std.debug.print("  {s}\n", .{s.name});
                     }
@@ -1014,6 +1047,7 @@ fn usage(builder: *std.Build, already_ran_build: bool, out_stream: anytype) !voi
         \\  --global-cache-dir [path]    Override path to global Zig cache directory
         \\  --zig-lib-dir [arg]          Override path to Zig lib directory
         \\  --build-runner [file]        Override path to build runner
+        \\  --seed [string]              Seed the prng used in the build runner
         \\  --debug-log [scope]          Enable debugging the compiler
         \\  --debug-pkg-config           Fail if unknown pkg-config flags encountered
         \\  --verbose-link               Enable compiler debug output for linking

lib/std/Build.zig

@@ -96,6 +96,10 @@ cache_root: Cache.Directory,
 global_cache_root: Cache.Directory,
 cache: *Cache,
 zig_lib_dir: ?LazyPath,
+// The hash of these bytes will be used as an init value for the build prng.
+// It allows receiving any input as seed, and printing it to output for
+// reproducibility.
+seed: []const u8,
 vcpkg_root: VcpkgRoot = .unattempted,
 pkg_config_pkg_list: ?(PkgConfigError![]const PkgConfigPkg) = null,
 args: ?[][]const u8 = null,
@@ -264,6 +268,9 @@ pub fn create(
             .description = "Remove build artifacts from prefix path",
         },
         .zig_lib_dir = null,
+        .seed = fmt_lib.allocPrint(self.allocator, "{x}", .{
+            @as(u64, @bitCast(std.time.microTimestamp())),
+        }) catch @panic("OOM"),
         .install_path = undefined,
         .args = null,
         .host = host,
@@ -341,6 +348,7 @@ fn createChildOnly(parent: *Build, dep_name: []const u8, build_root: Cache.Direc
         .global_cache_root = parent.global_cache_root,
         .cache = parent.cache,
         .zig_lib_dir = parent.zig_lib_dir,
+        .seed = parent.seed,
         .debug_log_scopes = parent.debug_log_scopes,
         .debug_compile_errors = parent.debug_compile_errors,
         .debug_pkg_config = parent.debug_pkg_config,