authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2024-03-18 23:51:43-07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2024-03-18 23:52:52-07:00
logc52a2c338d706862c2cc73f7321172eb24ab4430
treef3f946a879c432a66617d0bc24c7575b9e471928
parentfb812fc1fca2a752872e53047a15c0ff35091feb

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?

1 files changed, 42 insertions(+), 2 deletions(-)

lib/std/Build/Step/Run.zig+42-2
...@@ -168,13 +168,32 @@ pub fn addArtifactArg(self: *Run, artifact: *Step.Compile) void {...@@ -168,13 +168,32 @@ pub fn addArtifactArg(self: *Run, artifact: *Step.Compile) void {
168 self.argv.append(Arg{ .artifact = artifact }) catch @panic("OOM");168 self.argv.append(Arg{ .artifact = artifact }) catch @panic("OOM");
169}169}
170170
171/// This provides file path as a command line argument to the command being171/// Provides a file path as a command line argument to the command being run.
172/// run, and returns a LazyPath which can be used as inputs to other APIs172///
173/// Returns a `std.Build.LazyPath` which can be used as inputs to other APIs
173/// throughout the build system.174/// throughout the build system.
175///
176/// Related:
177/// * `addPrefixedOutputFileArg` - same thing but prepends a string to the argument
178/// * `addFileArg` - for input files given to the child process
174pub fn addOutputFileArg(self: *Run, basename: []const u8) std.Build.LazyPath {179pub fn addOutputFileArg(self: *Run, basename: []const u8) std.Build.LazyPath {
175 return self.addPrefixedOutputFileArg("", basename);180 return self.addPrefixedOutputFileArg("", basename);
176}181}
177182
183/// Provides a file path as a command line argument to the command being run.
184///
185/// For example, a prefix of "-o" and basename of "output.txt" will result in
186/// the child process seeing something like this: "-ozig-cache/.../output.txt"
187///
188/// The child process will see a single argument, regardless of whether the
189/// prefix or basename have spaces.
190///
191/// The returned `std.Build.LazyPath` can be used as inputs to other APIs
192/// throughout the build system.
193///
194/// Related:
195/// * `addOutputFileArg` - same thing but without the prefix
196/// * `addFileArg` - for input files given to the child process
178pub fn addPrefixedOutputFileArg(197pub fn addPrefixedOutputFileArg(
179 self: *Run,198 self: *Run,
180 prefix: []const u8,199 prefix: []const u8,
...@@ -197,10 +216,31 @@ pub fn addPrefixedOutputFileArg(...@@ -197,10 +216,31 @@ pub fn addPrefixedOutputFileArg(
197 return .{ .generated = &output.generated_file };216 return .{ .generated = &output.generated_file };
198}217}
199218
219/// Appends an input file to the command line arguments.
220///
221/// The child process will see a file path. Modifications to this file will be
222/// detected as a cache miss in subsequent builds, causing the child process to
223/// be re-executed.
224///
225/// Related:
226/// * `addPrefixedFileArg` - same thing but prepends a string to the argument
227/// * `addOutputFileArg` - for files generated by the child process
200pub fn addFileArg(self: *Run, lp: std.Build.LazyPath) void {228pub fn addFileArg(self: *Run, lp: std.Build.LazyPath) void {
201 self.addPrefixedFileArg("", lp);229 self.addPrefixedFileArg("", lp);
202}230}
203231
232/// Appends an input file to the command line arguments prepended with a string.
233///
234/// For example, a prefix of "-F" will result in the child process seeing something
235/// like this: "-Fexample.txt"
236///
237/// The child process will see a single argument, even if the prefix has
238/// spaces. Modifications to this file will be detected as a cache miss in
239/// subsequent builds, causing the child process to be re-executed.
240///
241/// Related:
242/// * `addFileArg` - same thing but without the prefix
243/// * `addOutputFileArg` - for files generated by the child process
204pub fn addPrefixedFileArg(self: *Run, prefix: []const u8, lp: std.Build.LazyPath) void {244pub fn addPrefixedFileArg(self: *Run, prefix: []const u8, lp: std.Build.LazyPath) void {
205 const b = self.step.owner;245 const b = self.step.owner;
206246