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:
599599 self.h_dir = self.pathJoin(&h_list);
600600}
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`.
602607pub fn addOptions(self: *Build) *Step.Options {
603608 return Step.Options.create(self);
604609}
......@@ -1031,6 +1036,11 @@ fn makeUninstall(uninstall_step: *Step, prog_node: *std.Progress.Node) anyerror!
10311036 // TODO remove empty directories
10321037}
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.
10341044pub fn option(self: *Build, comptime T: type, name_raw: []const u8, description_raw: []const u8) ?T {
10351045 const name = self.dupe(name_raw);
10361046 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)
318318 return addImport(m, name, module);
319319}
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")`.
321324pub fn addOptions(m: *Module, module_name: []const u8, options: *Step.Options) void {
322325 addImport(m, module_name, options.createModule());
323326}
lib/std/Build/Step/Options.zig+2
......@@ -198,6 +198,8 @@ pub fn createModule(self: *Options) *std.Build.Module {
198198/// deprecated: use `getOutput`
199199pub 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.
201203pub fn getOutput(self: *Options) LazyPath {
202204 return .{ .generated = &self.generated_file };
203205}