Build: cleanup

 * `doc/langref` formatting
 * upgrade `.{ .path = "..." }` to `b.path("...")`
 * avoid using arguments named `self`
 * make `Build.Step.Id` usage more consistent
 * add `Build.pathResolve`
 * use `pathJoin` and `pathResolve` everywhere
 * make sure `Build.LazyPath.getPath2` returns an absolute path

1 files changed, 58 insertions, 58 deletions

diff --git a/lib/std/Build/Step/WriteFile.zig b/lib/std/Build/Step/WriteFile.zig
index 0bec300957..875ddbfdbe 100644
--- a/lib/std/Build/Step/WriteFile.zig
+++ b/lib/std/Build/Step/WriteFile.zig
@@ -23,15 +23,15 @@ directories: std.ArrayListUnmanaged(*Directory),
 output_source_files: std.ArrayListUnmanaged(OutputSourceFile),
 generated_directory: std.Build.GeneratedFile,
 
-pub const base_id = .write_file;
+pub const base_id: Step.Id = .write_file;
 
 pub const File = struct {
     generated_file: std.Build.GeneratedFile,
     sub_path: []const u8,
     contents: Contents,
 
-    pub fn getPath(self: *File) std.Build.LazyPath {
-        return .{ .generated = &self.generated_file };
+    pub fn getPath(file: *File) std.Build.LazyPath {
+        return .{ .generated = &file.generated_file };
     }
 };
 
@@ -49,16 +49,16 @@ pub const Directory = struct {
         /// `exclude_extensions` takes precedence over `include_extensions`.
         include_extensions: ?[]const []const u8 = null,
 
-        pub fn dupe(self: Options, b: *std.Build) Options {
+        pub fn dupe(opts: Options, b: *std.Build) Options {
             return .{
-                .exclude_extensions = b.dupeStrings(self.exclude_extensions),
-                .include_extensions = if (self.include_extensions) |incs| b.dupeStrings(incs) else null,
+                .exclude_extensions = b.dupeStrings(opts.exclude_extensions),
+                .include_extensions = if (opts.include_extensions) |incs| b.dupeStrings(incs) else null,
             };
         }
     };
 
-    pub fn getPath(self: *Directory) std.Build.LazyPath {
-        return .{ .generated = &self.generated_dir };
+    pub fn getPath(dir: *Directory) std.Build.LazyPath {
+        return .{ .generated = &dir.generated_dir };
     }
 };
 
@@ -73,10 +73,10 @@ pub const Contents = union(enum) {
 };
 
 pub fn create(owner: *std.Build) *WriteFile {
-    const wf = owner.allocator.create(WriteFile) catch @panic("OOM");
-    wf.* = .{
+    const write_file = owner.allocator.create(WriteFile) catch @panic("OOM");
+    write_file.* = .{
         .step = Step.init(.{
-            .id = .write_file,
+            .id = base_id,
             .name = "WriteFile",
             .owner = owner,
             .makeFn = make,
@@ -84,22 +84,22 @@ pub fn create(owner: *std.Build) *WriteFile {
         .files = .{},
         .directories = .{},
         .output_source_files = .{},
-        .generated_directory = .{ .step = &wf.step },
+        .generated_directory = .{ .step = &write_file.step },
     };
-    return wf;
+    return write_file;
 }
 
-pub fn add(wf: *WriteFile, sub_path: []const u8, bytes: []const u8) std.Build.LazyPath {
-    const b = wf.step.owner;
+pub fn add(write_file: *WriteFile, sub_path: []const u8, bytes: []const u8) std.Build.LazyPath {
+    const b = write_file.step.owner;
     const gpa = b.allocator;
     const file = gpa.create(File) catch @panic("OOM");
     file.* = .{
-        .generated_file = .{ .step = &wf.step },
+        .generated_file = .{ .step = &write_file.step },
         .sub_path = b.dupePath(sub_path),
         .contents = .{ .bytes = b.dupe(bytes) },
     };
-    wf.files.append(gpa, file) catch @panic("OOM");
-    wf.maybeUpdateName();
+    write_file.files.append(gpa, file) catch @panic("OOM");
+    write_file.maybeUpdateName();
     return file.getPath();
 }
 
@@ -110,19 +110,19 @@ pub fn add(wf: *WriteFile, sub_path: []const u8, bytes: []const u8) std.Build.La
 /// include sub-directories, in which case this step will ensure the
 /// required sub-path exists.
 /// This is the option expected to be used most commonly with `addCopyFile`.
-pub fn addCopyFile(wf: *WriteFile, source: std.Build.LazyPath, sub_path: []const u8) std.Build.LazyPath {
-    const b = wf.step.owner;
+pub fn addCopyFile(write_file: *WriteFile, source: std.Build.LazyPath, sub_path: []const u8) std.Build.LazyPath {
+    const b = write_file.step.owner;
     const gpa = b.allocator;
     const file = gpa.create(File) catch @panic("OOM");
     file.* = .{
-        .generated_file = .{ .step = &wf.step },
+        .generated_file = .{ .step = &write_file.step },
         .sub_path = b.dupePath(sub_path),
         .contents = .{ .copy = source },
     };
-    wf.files.append(gpa, file) catch @panic("OOM");
+    write_file.files.append(gpa, file) catch @panic("OOM");
 
-    wf.maybeUpdateName();
-    source.addStepDependencies(&wf.step);
+    write_file.maybeUpdateName();
+    source.addStepDependencies(&write_file.step);
     return file.getPath();
 }
 
@@ -130,24 +130,24 @@ pub fn addCopyFile(wf: *WriteFile, source: std.Build.LazyPath, sub_path: []const
 /// relative to this step's generated directory.
 /// The returned value is a lazy path to the generated subdirectory.
 pub fn addCopyDirectory(
-    wf: *WriteFile,
+    write_file: *WriteFile,
     source: std.Build.LazyPath,
     sub_path: []const u8,
     options: Directory.Options,
 ) std.Build.LazyPath {
-    const b = wf.step.owner;
+    const b = write_file.step.owner;
     const gpa = b.allocator;
     const dir = gpa.create(Directory) catch @panic("OOM");
     dir.* = .{
         .source = source.dupe(b),
         .sub_path = b.dupePath(sub_path),
         .options = options.dupe(b),
-        .generated_dir = .{ .step = &wf.step },
+        .generated_dir = .{ .step = &write_file.step },
     };
-    wf.directories.append(gpa, dir) catch @panic("OOM");
+    write_file.directories.append(gpa, dir) catch @panic("OOM");
 
-    wf.maybeUpdateName();
-    source.addStepDependencies(&wf.step);
+    write_file.maybeUpdateName();
+    source.addStepDependencies(&write_file.step);
     return dir.getPath();
 }
 
@@ -156,13 +156,13 @@ pub fn addCopyDirectory(
 /// used as part of the normal build process, but as a utility occasionally
 /// run by a developer with intent to modify source files and then commit
 /// those changes to version control.
-pub fn addCopyFileToSource(wf: *WriteFile, source: std.Build.LazyPath, sub_path: []const u8) void {
-    const b = wf.step.owner;
-    wf.output_source_files.append(b.allocator, .{
+pub fn addCopyFileToSource(write_file: *WriteFile, source: std.Build.LazyPath, sub_path: []const u8) void {
+    const b = write_file.step.owner;
+    write_file.output_source_files.append(b.allocator, .{
         .contents = .{ .copy = source },
         .sub_path = sub_path,
     }) catch @panic("OOM");
-    source.addStepDependencies(&wf.step);
+    source.addStepDependencies(&write_file.step);
 }
 
 /// A path relative to the package root.
@@ -170,9 +170,9 @@ pub fn addCopyFileToSource(wf: *WriteFile, source: std.Build.LazyPath, sub_path:
 /// used as part of the normal build process, but as a utility occasionally
 /// run by a developer with intent to modify source files and then commit
 /// those changes to version control.
-pub fn addBytesToSource(wf: *WriteFile, bytes: []const u8, sub_path: []const u8) void {
-    const b = wf.step.owner;
-    wf.output_source_files.append(b.allocator, .{
+pub fn addBytesToSource(write_file: *WriteFile, bytes: []const u8, sub_path: []const u8) void {
+    const b = write_file.step.owner;
+    write_file.output_source_files.append(b.allocator, .{
         .contents = .{ .bytes = bytes },
         .sub_path = sub_path,
     }) catch @panic("OOM");
@@ -180,20 +180,20 @@ pub fn addBytesToSource(wf: *WriteFile, bytes: []const u8, sub_path: []const u8)
 
 /// Returns a `LazyPath` representing the base directory that contains all the
 /// files from this `WriteFile`.
-pub fn getDirectory(wf: *WriteFile) std.Build.LazyPath {
-    return .{ .generated = &wf.generated_directory };
+pub fn getDirectory(write_file: *WriteFile) std.Build.LazyPath {
+    return .{ .generated = &write_file.generated_directory };
 }
 
-fn maybeUpdateName(wf: *WriteFile) void {
-    if (wf.files.items.len == 1 and wf.directories.items.len == 0) {
+fn maybeUpdateName(write_file: *WriteFile) void {
+    if (write_file.files.items.len == 1 and write_file.directories.items.len == 0) {
         // First time adding a file; update name.
-        if (std.mem.eql(u8, wf.step.name, "WriteFile")) {
-            wf.step.name = wf.step.owner.fmt("WriteFile {s}", .{wf.files.items[0].sub_path});
+        if (std.mem.eql(u8, write_file.step.name, "WriteFile")) {
+            write_file.step.name = write_file.step.owner.fmt("WriteFile {s}", .{write_file.files.items[0].sub_path});
         }
-    } else if (wf.directories.items.len == 1 and wf.files.items.len == 0) {
+    } else if (write_file.directories.items.len == 1 and write_file.files.items.len == 0) {
         // First time adding a directory; update name.
-        if (std.mem.eql(u8, wf.step.name, "WriteFile")) {
-            wf.step.name = wf.step.owner.fmt("WriteFile {s}", .{wf.directories.items[0].sub_path});
+        if (std.mem.eql(u8, write_file.step.name, "WriteFile")) {
+            write_file.step.name = write_file.step.owner.fmt("WriteFile {s}", .{write_file.directories.items[0].sub_path});
         }
     }
 }
@@ -201,14 +201,14 @@ fn maybeUpdateName(wf: *WriteFile) void {
 fn make(step: *Step, prog_node: *std.Progress.Node) !void {
     _ = prog_node;
     const b = step.owner;
-    const wf: *WriteFile = @fieldParentPtr("step", step);
+    const write_file: *WriteFile = @fieldParentPtr("step", step);
 
     // Writing to source files is kind of an extra capability of this
     // WriteFile - arguably it should be a different step. But anyway here
     // it is, it happens unconditionally and does not interact with the other
     // files here.
     var any_miss = false;
-    for (wf.output_source_files.items) |output_source_file| {
+    for (write_file.output_source_files.items) |output_source_file| {
         if (fs.path.dirname(output_source_file.sub_path)) |dirname| {
             b.build_root.handle.makePath(dirname) catch |err| {
                 return step.fail("unable to make path '{}{s}': {s}", .{
@@ -226,7 +226,7 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
                 any_miss = true;
             },
             .copy => |file_source| {
-                const source_path = file_source.getPath(b);
+                const source_path = file_source.getPath2(b, step);
                 const prev_status = fs.Dir.updateFile(
                     fs.cwd(),
                     source_path,
@@ -258,18 +258,18 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
     // in a non-backwards-compatible way.
     man.hash.add(@as(u32, 0xd767ee59));
 
-    for (wf.files.items) |file| {
+    for (write_file.files.items) |file| {
         man.hash.addBytes(file.sub_path);
         switch (file.contents) {
             .bytes => |bytes| {
                 man.hash.addBytes(bytes);
             },
             .copy => |file_source| {
-                _ = try man.addFile(file_source.getPath(b), null);
+                _ = try man.addFile(file_source.getPath2(b, step), null);
             },
         }
     }
-    for (wf.directories.items) |dir| {
+    for (write_file.directories.items) |dir| {
         man.hash.addBytes(dir.source.getPath2(b, step));
         man.hash.addBytes(dir.sub_path);
         for (dir.options.exclude_extensions) |ext| man.hash.addBytes(ext);
@@ -278,19 +278,19 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
 
     if (try step.cacheHit(&man)) {
         const digest = man.final();
-        for (wf.files.items) |file| {
+        for (write_file.files.items) |file| {
             file.generated_file.path = try b.cache_root.join(b.allocator, &.{
                 "o", &digest, file.sub_path,
             });
         }
-        wf.generated_directory.path = try b.cache_root.join(b.allocator, &.{ "o", &digest });
+        write_file.generated_directory.path = try b.cache_root.join(b.allocator, &.{ "o", &digest });
         return;
     }
 
     const digest = man.final();
     const cache_path = "o" ++ fs.path.sep_str ++ digest;
 
-    wf.generated_directory.path = try b.cache_root.join(b.allocator, &.{ "o", &digest });
+    write_file.generated_directory.path = try b.cache_root.join(b.allocator, &.{ "o", &digest });
 
     var cache_dir = b.cache_root.handle.makeOpenPath(cache_path, .{}) catch |err| {
         return step.fail("unable to make path '{}{s}': {s}", .{
@@ -301,7 +301,7 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
 
     const cwd = fs.cwd();
 
-    for (wf.files.items) |file| {
+    for (write_file.files.items) |file| {
         if (fs.path.dirname(file.sub_path)) |dirname| {
             cache_dir.makePath(dirname) catch |err| {
                 return step.fail("unable to make path '{}{s}{c}{s}': {s}", .{
@@ -318,7 +318,7 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
                 };
             },
             .copy => |file_source| {
-                const source_path = file_source.getPath(b);
+                const source_path = file_source.getPath2(b, step);
                 const prev_status = fs.Dir.updateFile(
                     cwd,
                     source_path,
@@ -347,7 +347,7 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
             cache_path, file.sub_path,
         });
     }
-    for (wf.directories.items) |dir| {
+    for (write_file.directories.items) |dir| {
         const full_src_dir_path = dir.source.getPath2(b, step);
         const dest_dirname = dir.sub_path;