authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2024-01-18 21:31:45-07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2024-01-18 22:01:09-07:00
logab82132749f24702c215545212dd83538a04cdb9
tree6422e506dfe395c77f677ccf8e2ee6b90997115d
parent56db624643bb506d2b8fa9d81f4146c1b1f4e3c3

zig build: add doc comments for functions related to options

closes #18204

3 files changed, 15 insertions(+), 0 deletions(-)

lib/std/Build.zig+10
...@@ -599,6 +599,11 @@ pub fn resolveInstallPrefix(self: *Build, install_prefix: ?[]const u8, dir_list:...@@ -599,6 +599,11 @@ pub fn resolveInstallPrefix(self: *Build, install_prefix: ?[]const u8, dir_list:
599 self.h_dir = self.pathJoin(&h_list);599 self.h_dir = self.pathJoin(&h_list);
600}600}
601601
602/// Create a set of key-value pairs that can be converted into a Zig source
603/// file and then inserted into a Zig compilation's module table for importing.
604/// In other words, this provides a way to expose build.zig values to Zig
605/// source code with `@import`.
606/// Related: `Module.addOptions`.
602pub fn addOptions(self: *Build) *Step.Options {607pub fn addOptions(self: *Build) *Step.Options {
603 return Step.Options.create(self);608 return Step.Options.create(self);
604}609}
...@@ -1031,6 +1036,11 @@ fn makeUninstall(uninstall_step: *Step, prog_node: *std.Progress.Node) anyerror!...@@ -1031,6 +1036,11 @@ fn makeUninstall(uninstall_step: *Step, prog_node: *std.Progress.Node) anyerror!
1031 // TODO remove empty directories1036 // TODO remove empty directories
1032}1037}
10331038
1039/// Creates a configuration option to be passed to the build.zig script.
1040/// When a user directly runs `zig build`, they can set these options with `-D` arguments.
1041/// When a project depends on a Zig package as a dependency, it programmatically sets
1042/// these options when calling the dependency's build.zig script as a function.
1043/// `null` is returned when an option is left to default.
1034pub fn option(self: *Build, comptime T: type, name_raw: []const u8, description_raw: []const u8) ?T {1044pub fn option(self: *Build, comptime T: type, name_raw: []const u8, description_raw: []const u8) ?T {
1035 const name = self.dupe(name_raw);1045 const name = self.dupe(name_raw);
1036 const description = self.dupe(description_raw);1046 const description = self.dupe(description_raw);
lib/std/Build/Module.zig+3
...@@ -318,6 +318,9 @@ pub fn addAnonymousImport(m: *Module, name: []const u8, options: CreateOptions)...@@ -318,6 +318,9 @@ pub fn addAnonymousImport(m: *Module, name: []const u8, options: CreateOptions)
318 return addImport(m, name, module);318 return addImport(m, name, module);
319}319}
320320
321/// Converts a set of key-value pairs into a Zig source file, and then inserts it into
322/// the Module's import table with the specified name. This makes the options importable
323/// via `@import("module_name")`.
321pub fn addOptions(m: *Module, module_name: []const u8, options: *Step.Options) void {324pub fn addOptions(m: *Module, module_name: []const u8, options: *Step.Options) void {
322 addImport(m, module_name, options.createModule());325 addImport(m, module_name, options.createModule());
323}326}
lib/std/Build/Step/Options.zig+2
...@@ -198,6 +198,8 @@ pub fn createModule(self: *Options) *std.Build.Module {...@@ -198,6 +198,8 @@ pub fn createModule(self: *Options) *std.Build.Module {
198/// deprecated: use `getOutput`198/// deprecated: use `getOutput`
199pub const getSource = getOutput;199pub const getSource = getOutput;
200200
201/// Returns the main artifact of this Build Step which is a Zig source file
202/// generated from the key-value pairs of the Options.
201pub fn getOutput(self: *Options) LazyPath {203pub fn getOutput(self: *Options) LazyPath {
202 return .{ .generated = &self.generated_file };204 return .{ .generated = &self.generated_file };
203}205}