build: split --verbose to specific flags

Usage (excluding initialization) of `build.verbose` appears in two
files:

1. lib/std/Build.zig
2. lib/std/Build/Step.zig

As it turns out only Step.zig is relevant in the new context of
`--verbose-spawn`. The verbose references in Build.zig are through
`makeUninstall` and `truncateFile`. The first of which is a bunch of
deletion operations, and the second of which only got called from
InstallDir.zig.

The `truncateFile` operation in itself is general enough to not depend
on a specific flag and the log call is therefore hoisted to the
InstallDir.zig callsite. The logging in InstallDir is then enabled by
a new parameter `--verbose-install`. I also took the liberty of adding
logging to the result of updateFile operations as well under this flag.
The updateFile logic is also used in InstallFile and InstallArtifact, so
the helper `handleVerboseInstallUpdateFile` was created and added to all
call site results.

Regarding audit of child process invocations in Build.zig and default
Steps:

`execAllowFail` is the child process spawning part of the Build API that
did not log invocations, so a call to `handleVerboseSpawn2` was added.

The other APIs are `evalZigProcess` and `evalChildProcess`, but they
already use the `handleVerboseSpawn` helper.

Closes ziglang#14970

Author: tjog

lib/build_runner.zig

@@ -114,8 +114,12 @@ pub fn main() !void {
                     usageAndErr(builder, false, stderr_stream);
             }
         } else if (mem.startsWith(u8, arg, "-")) {
-            if (mem.eql(u8, arg, "--verbose")) {
-                builder.verbose = true;
+            if (mem.eql(u8, arg, "--verbose-spawn")) {
+                builder.verbose_spawn = true;
+            } else if (mem.eql(u8, arg, "--verbose-install")) {
+                builder.verbose_install = true;
+            } else if (mem.eql(u8, arg, "--verbose-uninstall")) {
+                builder.verbose_uninstall = true;
             } else if (mem.eql(u8, arg, "-h") or mem.eql(u8, arg, "--help")) {
                 return usage(builder, false, stdout_stream);
             } else if (mem.eql(u8, arg, "-p") or mem.eql(u8, arg, "--prefix")) {
@@ -970,7 +974,9 @@ fn usage(builder: *std.Build, already_ran_build: bool, out_stream: anytype) !voi
         \\
         \\  -h, --help                   Print this help and exit
         \\  -l, --list-steps             Print available steps
-        \\  --verbose                    Print commands before executing them
+        \\  --verbose-spawn              Print to stderr the commandline before spawning any child process
+        \\  --verbose-install            Print to stderr more info during install step (copying build artifacts)
+        \\  --verbose-uninstall          Print to stderr more info during uninstall step (removing build artifacts)
         \\  --color [auto|off|on]        Enable or disable colored error messages
         \\  --summary [mode]             Control the printing of the build summary
         \\    all                        Print the build summary in its entirety

lib/std/Build.zig

@@ -64,7 +64,9 @@ allocator: Allocator,
 user_input_options: UserInputOptionsMap,
 available_options_map: AvailableOptionsMap,
 available_options_list: ArrayList(AvailableOption),
-verbose: bool,
+verbose_spawn: bool,
+verbose_install: bool,
+verbose_uninstall: bool,
 verbose_link: bool,
 verbose_cc: bool,
 verbose_air: bool,
@@ -222,7 +224,9 @@ pub fn create(
         .cache_root = cache_root,
         .global_cache_root = global_cache_root,
         .cache = cache,
-        .verbose = false,
+        .verbose_spawn = false,
+        .verbose_install = false,
+        .verbose_uninstall = false,
         .verbose_link = false,
         .verbose_cc = false,
         .verbose_air = false,
@@ -311,7 +315,9 @@ fn createChildOnly(parent: *Build, dep_name: []const u8, build_root: Cache.Direc
         .user_input_options = UserInputOptionsMap.init(allocator),
         .available_options_map = AvailableOptionsMap.init(allocator),
         .available_options_list = ArrayList(AvailableOption).init(allocator),
-        .verbose = parent.verbose,
+        .verbose_spawn = parent.verbose_spawn,
+        .verbose_install = parent.verbose_install,
+        .verbose_uninstall = parent.verbose_uninstall,
         .verbose_link = parent.verbose_link,
         .verbose_cc = parent.verbose_cc,
         .verbose_air = parent.verbose_air,
@@ -796,7 +802,8 @@ fn makeUninstall(uninstall_step: *Step, prog_node: *std.Progress.Node) anyerror!
 
     for (self.installed_files.items) |installed_file| {
         const full_path = self.getInstallPath(installed_file.dir, installed_file.path);
-        if (self.verbose) {
+        if (self.verbose_uninstall) {
+            // log implementation must acquire stdErr mutex during parallel builds
             log.info("rm {s}", .{full_path});
         }
         fs.cwd().deleteTree(full_path) catch {};
@@ -1336,10 +1343,7 @@ pub fn pushInstalledFile(self: *Build, dir: InstallDir, dest_rel_path: []const u
     self.installed_files.append(file.dupe(self)) catch @panic("OOM");
 }
 
-pub fn truncateFile(self: *Build, dest_path: []const u8) !void {
-    if (self.verbose) {
-        log.info("truncate {s}", .{dest_path});
-    }
+pub fn truncateFile(dest_path: []const u8) !void {
     const cwd = fs.cwd();
     var src_file = cwd.createFile(dest_path, .{}) catch |err| switch (err) {
         error.FileNotFound => blk: {
@@ -1429,6 +1433,7 @@ pub fn execAllowFail(
     child.stderr_behavior = stderr_behavior;
     child.env_map = self.env_map;
 
+    try Step.handleVerboseSpawn2(self, child.cwd, child.env_map, argv);
     try child.spawn();
 
     const stdout = child.stdout.?.reader().readAllAlloc(self.allocator, max_output_size) catch {

lib/std/Build/Step.zig

@@ -263,7 +263,7 @@ pub fn evalChildProcess(s: *Step, argv: []const []const u8) !void {
     const arena = s.owner.allocator;
 
     try handleChildProcUnsupported(s, null, argv);
-    try handleVerbose(s.owner, null, argv);
+    try handleVerboseSpawn(s.owner, null, argv);
 
     const result = std.ChildProcess.exec(.{
         .allocator = arena,
@@ -301,7 +301,7 @@ pub fn evalZigProcess(
     const gpa = arena;
 
     try handleChildProcUnsupported(s, null, argv);
-    try handleVerbose(s.owner, null, argv);
+    try handleVerboseSpawn(s.owner, null, argv);
 
     var child = std.ChildProcess.init(argv, arena);
     child.env_map = b.env_map;
@@ -437,22 +437,22 @@ fn sendMessage(file: std.fs.File, tag: std.zig.Client.Message.Tag) !void {
     try file.writeAll(std.mem.asBytes(&header));
 }
 
-pub fn handleVerbose(
+pub fn handleVerboseSpawn(
     b: *Build,
     opt_cwd: ?[]const u8,
     argv: []const []const u8,
 ) error{OutOfMemory}!void {
-    return handleVerbose2(b, opt_cwd, null, argv);
+    return handleVerboseSpawn2(b, opt_cwd, null, argv);
 }
 
-pub fn handleVerbose2(
+pub fn handleVerboseSpawn2(
     b: *Build,
     opt_cwd: ?[]const u8,
     opt_env: ?*const std.process.EnvMap,
     argv: []const []const u8,
 ) error{OutOfMemory}!void {
-    if (b.verbose) {
-        // Intention of verbose is to print all sub-process command lines to
+    if (b.verbose_spawn) {
+        // Intention of verbose_spawn is to print all sub-process command lines to
         // stderr before spawning them.
         const text = try allocPrintCmd2(b.allocator, opt_cwd, opt_env, argv);
         std.debug.print("{s}\n", .{text});
@@ -496,6 +496,20 @@ pub fn handleChildProcessTerm(
         },
     }
 }
+pub fn handleVerboseInstallUpdateFile(
+    b: *Build,
+    status_result: std.fs.PrevStatus,
+    dest_path: []const u8,
+) void {
+    if (b.verbose_install) {
+        // log implementation responsible for acquiring stdErr mutex
+        const action_was = switch (status_result) {
+            .fresh => "cached",
+            .stale => "update",
+        };
+        std.log.info("{s} {s}", .{ action_was, dest_path });
+    }
+}
 
 pub fn allocPrintCmd(
     arena: Allocator,

lib/std/Build/Step/InstallArtifact.zig

@@ -82,6 +82,7 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
                 full_src_path, full_dest_path, @errorName(err),
             });
         };
+        Step.handleVerboseInstallUpdateFile(dest_builder, p, full_dest_path);
         all_cached = all_cached and p == .fresh;
     }
 
@@ -102,6 +103,7 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
                 full_src_path, full_implib_path, @errorName(err),
             });
         };
+        Step.handleVerboseInstallUpdateFile(dest_builder, p, full_implib_path);
         all_cached = all_cached and p == .fresh;
     }
     if (self.pdb_dir) |pdb_dir| {
@@ -112,6 +114,7 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
                 full_src_path, full_pdb_path, @errorName(err),
             });
         };
+        Step.handleVerboseInstallUpdateFile(dest_builder, p, full_pdb_path);
         all_cached = all_cached and p == .fresh;
     }
     if (self.h_dir) |h_dir| {
@@ -122,6 +125,7 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
                 full_src_path, full_h_path, @errorName(err),
             });
         };
+        Step.handleVerboseInstallUpdateFile(dest_builder, p, full_h_path);
         all_cached = all_cached and p == .fresh;
     }
     self.artifact.installed_path = full_dest_path;

lib/std/Build/Step/InstallDir.zig

@@ -89,7 +89,11 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
             .file => {
                 for (self.options.blank_extensions) |ext| {
                     if (mem.endsWith(u8, entry.path, ext)) {
-                        try dest_builder.truncateFile(dest_path);
+                        if (dest_builder.verbose_install) {
+                            // log implementation responsible for acquiring stdErr mutex
+                            std.log.info("truncate {s}", .{dest_path});
+                        }
+                        try std.Build.truncateFile(dest_path);
                         continue :next_entry;
                     }
                 }
@@ -105,6 +109,7 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
                         src_builder.build_root, src_sub_path, dest_path, @errorName(err),
                     });
                 };
+                Step.handleVerboseInstallUpdateFile(dest_builder, prev_status, dest_path);
                 all_cached = all_cached and prev_status == .fresh;
             },
             else => continue,

lib/std/Build/Step/InstallFile.zig

@@ -53,5 +53,6 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
             full_src_path, full_dest_path, @errorName(err),
         });
     };
+    Step.handleVerboseInstallUpdateFile(dest_builder, prev, full_dest_path);
     step.result_cached = prev == .fresh;
 }

lib/std/Build/Step/Run.zig

@@ -607,7 +607,7 @@ fn runCommand(
     const arena = b.allocator;
 
     try step.handleChildProcUnsupported(self.cwd, argv);
-    try Step.handleVerbose2(step.owner, self.cwd, self.env_map, argv);
+    try Step.handleVerboseSpawn2(step.owner, self.cwd, self.env_map, argv);
 
     const allow_skip = switch (self.stdio) {
         .check, .zig_test => self.skip_foreign_checks,
@@ -734,7 +734,7 @@ fn runCommand(
                 self.addPathForDynLibs(exe);
             }
 
-            try Step.handleVerbose2(step.owner, self.cwd, self.env_map, interp_argv.items);
+            try Step.handleVerboseSpawn2(step.owner, self.cwd, self.env_map, interp_argv.items);
 
             break :term spawnChildAndCollect(self, interp_argv.items, has_side_effects, prog_node) catch |e| {
                 if (!self.failing_to_execute_foreign_is_an_error) return error.MakeSkipped;