build system: follow-up enhancements regarding LazyPath

* introduce LazyPath.cwd_relative variant and use it for --zig-lib-dir. closes #12685
* move overrideZigLibDir and setMainPkgPath to options fields set once
  and then never mutated.
* avoid introducing Build/util.zig
* use doc comments for deprecation notices so that they show up in
  generated documentation.
* introduce InstallArtifact.Options, accept it as a parameter to
  addInstallArtifact, and move override_dest_dir into it. Instead of
  configuring the installation via Compile step, configure the
  installation via the InstallArtifact step. In retrospect this is
  obvious.
* remove calls to pushInstalledFile in InstallArtifact. See #14943
* rewrite InstallArtifact to not incorrectly observe whether a Compile
  step has any generated outputs. InstallArtifact is meant to trigger
  output generation.
* fix child process evaluation code handling of `-fno-emit-bin`.
* don't store out_h_filename, out_ll_filename, etc., pointlessly. these
  are all just simple extensions appended to the root name.
* make emit_directory optional. It's possible to have nothing outputted,
  for example, if you're just type-checking.
* avoid passing -femit-foo/-fno-emit-foo when it is the default
* rename ConfigHeader.getTemplate to getOutput
* deprecate addOptionArtifact
* update the random number seed of Options step caching.
* avoid using `inline for` pointlessly
* avoid using `override_Dest_dir` pointlessly
* avoid emitting an executable pointlessly in test cases
* fix compiler_rt_panic test case warning about _start

Removes forceBuild and forceEmit. Let's consider these additions separately.
Nearly all of the usage sites were suspicious.

Author: andrewrk

build.zig

@@ -45,7 +45,8 @@ pub fn build(b: *std.Build) !void {
     const docgen_cmd = b.addRunArtifact(docgen_exe);
     docgen_cmd.addArgs(&.{ "--zig", b.zig_exe });
     if (b.zig_lib_dir) |p| {
-        docgen_cmd.addArgs(&.{ "--zig-lib-dir", b.pathFromRoot(p) });
+        docgen_cmd.addArg("--zig-lib-dir");
+        docgen_cmd.addFileArg(p);
     }
     docgen_cmd.addFileArg(.{ .path = "doc/langref.html.in" });
     const langref_file = docgen_cmd.addOutputFileArg("langref.html");
@@ -57,8 +58,8 @@ pub fn build(b: *std.Build) !void {
     const autodoc_test = b.addTest(.{
         .root_source_file = .{ .path = "lib/std/std.zig" },
         .target = target,
+        .zig_lib_dir = .{ .path = "lib" },
     });
-    autodoc_test.overrideZigLibDir(.{ .path = "lib" });
     const install_std_docs = b.addInstallDirectory(.{
         .source_dir = autodoc_test.getEmittedDocs(),
         .install_dir = .prefix,
@@ -87,8 +88,8 @@ pub fn build(b: *std.Build) !void {
         .name = "check-case",
         .root_source_file = .{ .path = "test/src/Cases.zig" },
         .optimize = optimize,
+        .main_pkg_path = .{ .path = "." },
     });
-    check_case_exe.setMainPkgPath(.{ .path = "." });
     check_case_exe.stack_size = stack_size;
     check_case_exe.single_threaded = single_threaded;
 
@@ -203,7 +204,7 @@ pub fn build(b: *std.Build) !void {
     );
 
     if (!no_bin) {
-        const install_exe = b.addInstallArtifact(exe);
+        const install_exe = b.addInstallArtifact(exe, .{});
         if (flat) {
             install_exe.dest_dir = .prefix;
         }
@@ -357,8 +358,8 @@ pub fn build(b: *std.Build) !void {
         else
             &[_][]const u8{ "-DTRACY_ENABLE=1", "-fno-sanitize=undefined" };
 
-        exe.addIncludePath(.{ .path = tracy_path });
-        exe.addCSourceFile(.{ .file = .{ .path = client_cpp }, .flags = tracy_c_flags });
+        exe.addIncludePath(.{ .cwd_relative = tracy_path });
+        exe.addCSourceFile(.{ .file = .{ .cwd_relative = client_cpp }, .flags = tracy_c_flags });
         if (!enable_llvm) {
             exe.linkSystemLibraryName("c++");
         }
@@ -597,7 +598,7 @@ fn addCmakeCfgOptionsToExe(
         // useful for package maintainers
         exe.headerpad_max_install_names = true;
     }
-    exe.addObjectFile(.{ .path = b.pathJoin(&[_][]const u8{
+    exe.addObjectFile(.{ .cwd_relative = b.pathJoin(&[_][]const u8{
         cfg.cmake_binary_dir,
         "zigcpp",
         b.fmt("{s}{s}{s}", .{
@@ -607,9 +608,9 @@ fn addCmakeCfgOptionsToExe(
         }),
     }) });
     assert(cfg.lld_include_dir.len != 0);
-    exe.addIncludePath(.{ .path = cfg.lld_include_dir });
-    exe.addIncludePath(.{ .path = cfg.llvm_include_dir });
-    exe.addLibraryPath(.{ .path = cfg.llvm_lib_dir });
+    exe.addIncludePath(.{ .cwd_relative = cfg.lld_include_dir });
+    exe.addIncludePath(.{ .cwd_relative = cfg.llvm_include_dir });
+    exe.addLibraryPath(.{ .cwd_relative = cfg.llvm_lib_dir });
     addCMakeLibraryList(exe, cfg.clang_libraries);
     addCMakeLibraryList(exe, cfg.lld_libraries);
     addCMakeLibraryList(exe, cfg.llvm_libraries);
@@ -665,7 +666,7 @@ fn addCmakeCfgOptionsToExe(
     }
 
     if (cfg.dia_guids_lib.len != 0) {
-        exe.addObjectFile(.{ .path = cfg.dia_guids_lib });
+        exe.addObjectFile(.{ .cwd_relative = cfg.dia_guids_lib });
     }
 }
 
@@ -726,7 +727,7 @@ fn addCxxKnownPath(
         }
         return error.RequiredLibraryNotFound;
     }
-    exe.addObjectFile(.{ .path = path_unpadded });
+    exe.addObjectFile(.{ .cwd_relative = path_unpadded });
 
     // TODO a way to integrate with system c++ include files here
     // c++ -E -Wp,-v -xc++ /dev/null
@@ -746,7 +747,7 @@ fn addCMakeLibraryList(exe: *std.Build.Step.Compile, list: []const u8) void {
         } else if (exe.target.isWindows() and mem.endsWith(u8, lib, ".lib") and !fs.path.isAbsolute(lib)) {
             exe.linkSystemLibrary(lib[0 .. lib.len - ".lib".len]);
         } else {
-            exe.addObjectFile(.{ .path = lib });
+            exe.addObjectFile(.{ .cwd_relative = lib });
         }
     }
 }

lib/build_runner.zig

@@ -188,10 +188,10 @@ pub fn main() !void {
                     usageAndErr(builder, false, stderr_stream);
                 };
             } else if (mem.eql(u8, arg, "--zig-lib-dir")) {
-                builder.zig_lib_dir = nextArg(args, &arg_idx) orelse {
+                builder.zig_lib_dir = .{ .cwd_relative = nextArg(args, &arg_idx) orelse {
                     std.debug.print("Expected argument after {s}\n\n", .{arg});
                     usageAndErr(builder, false, stderr_stream);
-                };
+                } };
             } 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});