std.Build: adjust temp files API

Remove the RemoveDir step with no replacement. This step had no valid
purpose. Mutating source files? That should be done with
UpdateSourceFiles step. Deleting temporary directories? That required
creating the tmp directories in the configure phase which is broken.
Deleting cached artifacts? That's going to cause problems.

Similarly, remove the `Build.makeTempPath` function. This was used to
create a temporary path in the configure place which, again, is the
wrong place to do it.

Instead, the WriteFile step has been updated with more functionality:

tmp mode: In this mode, the directory will be placed inside "tmp" rather
than "o", and caching will be skipped. During the `make` phase, the step
will always do all the file system operations, and on successful build
completion, the dir will be deleted along with all other tmp
directories. The directory is therefore eligible to be used for
mutations by other steps. `Build.addTempFiles` is introduced to
initialize a WriteFile step with this mode.

mutate mode: The operations will not be performed against a freshly
created directory, but instead act against a temporary directory.
`Build.addMutateFiles` is introduced to initialize a WriteFile step with
this mode.

`Build.tmpPath` is introduced, which is a shortcut for
`Build.addTempFiles` followed by `WriteFile.getDirectory`.

* give Cache a gpa rather than arena because that's what it asks for

lib/std/Build.zig

@@ -111,6 +111,7 @@ pub const ReleaseMode = enum {
 /// Settings that are here rather than in Build are not configurable per-package.
 pub const Graph = struct {
     io: Io,
+    /// Process lifetime.
     arena: Allocator,
     system_library_options: std.StringArrayHashMapUnmanaged(SystemLibraryMode) = .empty,
     system_package_mode: bool = false,
@@ -1057,6 +1058,38 @@ pub fn addNamedLazyPath(b: *Build, name: []const u8, lp: LazyPath) void {
     b.named_lazy_paths.put(b.dupe(name), lp.dupe(b)) catch @panic("OOM");
 }
 
+/// Creates a step for mutating files inside a temporary directory created lazily
+/// and automatically cleaned up upon successful build.
+///
+/// The directory will be placed inside "tmp" rather than "o", and caching will
+/// be skipped. During the `make` phase, the step will always do all the file
+/// system operations, and on successful build completion, the dir will be
+/// deleted along with all other tmp directories. The directory is therefore
+/// eligible to be used for mutations by other steps.
+///
+/// See also:
+/// * `addWriteFiles`
+/// * `addMutateFiles`
+pub fn addTempFiles(b: *Build) *Step.WriteFile {
+    const wf = addWriteFiles(b);
+    wf.mode = .tmp;
+    return wf;
+}
+
+/// Creates a step for mutating temporary directories created with `addTempFiles`.
+///
+/// Consider instead `addWriteFiles` which is for creating a cached directory
+/// of files to operate on.
+///
+/// This should only be used with a `tmp_path` obtained via `addTempFiles` or
+/// `tmpPath`.
+pub fn addMutateFiles(b: *Build, tmp_path: LazyPath) *Step.WriteFile {
+    const wf = addWriteFiles(b);
+    wf.mode = .{ .mutate = tmp_path };
+    tmp_path.addStepDependencies(&wf.step);
+    return wf;
+}
+
 pub fn addWriteFiles(b: *Build) *Step.WriteFile {
     return Step.WriteFile.create(b);
 }
@@ -1065,10 +1098,6 @@ pub fn addUpdateSourceFiles(b: *Build) *Step.UpdateSourceFiles {
     return Step.UpdateSourceFiles.create(b);
 }
 
-pub fn addRemoveDirTree(b: *Build, dir_path: LazyPath) *Step.RemoveDir {
-    return Step.RemoveDir.create(b, dir_path);
-}
-
 pub fn addFail(b: *Build, error_msg: []const u8) *Step.Fail {
     return Step.Fail.create(b, error_msg);
 }
@@ -2235,9 +2264,8 @@ pub fn runBuild(b: *Build, build_zig: anytype) anyerror!void {
 /// A file that is generated by a build step.
 /// This struct is an interface that is meant to be used with `@fieldParentPtr` to implement the actual path logic.
 pub const GeneratedFile = struct {
-    /// The step that generates the file
+    /// The step that generates the file.
     step: *Step,
-
     /// The path to the generated file. Must be either absolute or relative to the build runner cwd.
     /// This value must be set in the `fn make()` of the `step` and must not be `null` afterwards.
     path: ?[]const u8 = null,
@@ -2321,9 +2349,11 @@ pub const LazyPath = union(enum) {
 
     /// An absolute path or a path relative to the current working directory of
     /// the build runner process.
+    ///
     /// This is uncommon but used for system environment paths such as `--zig-lib-dir` which
     /// ignore the file system path of build.zig and instead are relative to the directory from
     /// which `zig build` was invoked.
+    ///
     /// Use of this tag indicates a dependency on the host system.
     cwd_relative: []const u8,
 
@@ -2646,19 +2676,12 @@ pub const InstallDir = union(enum) {
     }
 };
 
-/// This function is intended to be called in the `configure` phase only.
-/// It returns an absolute directory path, which is potentially going to be a
-/// source of API breakage in the future, so keep that in mind when using this
-/// function.
-pub fn makeTempPath(b: *Build) []const u8 {
-    const io = b.graph.io;
-    const rand_int = std.crypto.random.int(u64);
-    const tmp_dir_sub_path = "tmp" ++ fs.path.sep_str ++ std.fmt.hex(rand_int);
-    const result_path = b.cache_root.join(b.allocator, &.{tmp_dir_sub_path}) catch @panic("OOM");
-    b.cache_root.handle.createDirPath(io, tmp_dir_sub_path) catch |err| {
-        std.debug.print("unable to make tmp path '{s}': {t}\n", .{ result_path, err });
-    };
-    return result_path;
+/// Creates a path leading to a directory inside "tmp" subdirectory of
+/// `cache_root` which is created on demand and cleaned up by the build runner
+/// upon success.
+pub fn tmpPath(b: *Build) LazyPath {
+    const wf = b.addTempFiles();
+    return wf.getDirectory();
 }
 
 /// A pair of target query and fully resolved target.