zig

commit c52a2c338d706862c2cc73f7321172eb24ab4430 (tree)
parent fb812fc1fca2a752872e53047a15c0ff35091feb
Author: Andrew Kelley <andrew@ziglang.org>
Date:   Mon, 18 Mar 2024 23:51:43 -0700

std.Build.Step.Run: documentation for addFileArg and friends

Someone on IRC got these functions mixed up, and it sure would have been
helpful to have these docs in the first place, eh?

Diffstat:
M
lib/std/Build/Step/Run.zig
 | 
44
++++++++++++++++++++++++++++++++++++++++++--

1 file changed, 42 insertions(+), 2 deletions(-)
diff --git a/lib/std/Build/Step/Run.zig b/lib/std/Build/Step/Run.zig
@@ -168,13 +168,32 @@ pub fn addArtifactArg(self: *Run, artifact: *Step.Compile) void {
     self.argv.append(Arg{ .artifact = artifact }) catch @panic("OOM");
 }
 
-/// This provides file path as a command line argument to the command being
-/// run, and returns a LazyPath which can be used as inputs to other APIs
+/// Provides a file path as a command line argument to the command being run.
+///
+/// Returns a `std.Build.LazyPath` which can be used as inputs to other APIs
 /// throughout the build system.
+///
+/// Related:
+/// * `addPrefixedOutputFileArg` - same thing but prepends a string to the argument
+/// * `addFileArg` - for input files given to the child process
 pub fn addOutputFileArg(self: *Run, basename: []const u8) std.Build.LazyPath {
     return self.addPrefixedOutputFileArg("", basename);
 }
 
+/// Provides a file path as a command line argument to the command being run.
+///
+/// For example, a prefix of "-o" and basename of "output.txt" will result in
+/// the child process seeing something like this: "-ozig-cache/.../output.txt"
+///
+/// The child process will see a single argument, regardless of whether the
+/// prefix or basename have spaces.
+///
+/// The returned `std.Build.LazyPath` can be used as inputs to other APIs
+/// throughout the build system.
+///
+/// Related:
+/// * `addOutputFileArg` - same thing but without the prefix
+/// * `addFileArg` - for input files given to the child process
 pub fn addPrefixedOutputFileArg(
     self: *Run,
     prefix: []const u8,
@@ -197,10 +216,31 @@ pub fn addPrefixedOutputFileArg(
     return .{ .generated = &output.generated_file };
 }
 
+/// Appends an input file to the command line arguments.
+///
+/// The child process will see a file path. Modifications to this file will be
+/// detected as a cache miss in subsequent builds, causing the child process to
+/// be re-executed.
+///
+/// Related:
+/// * `addPrefixedFileArg` - same thing but prepends a string to the argument
+/// * `addOutputFileArg` - for files generated by the child process
 pub fn addFileArg(self: *Run, lp: std.Build.LazyPath) void {
     self.addPrefixedFileArg("", lp);
 }
 
+/// Appends an input file to the command line arguments prepended with a string.
+///
+/// For example, a prefix of "-F" will result in the child process seeing something
+/// like this: "-Fexample.txt"
+///
+/// The child process will see a single argument, even if the prefix has
+/// spaces. Modifications to this file will be detected as a cache miss in
+/// subsequent builds, causing the child process to be re-executed.
+///
+/// Related:
+/// * `addFileArg` - same thing but without the prefix
+/// * `addOutputFileArg` - for files generated by the child process
 pub fn addPrefixedFileArg(self: *Run, prefix: []const u8, lp: std.Build.LazyPath) void {
     const b = self.step.owner;