authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2026-05-28 17:49:46-07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2026-06-29 23:50:18-07:00
log6a052277c37dff298b1ca18c4f07c0facf1beecf
tree08840b32fd1d914151c13b2c97b834ebf0ea746e
parent1d1193aa7b015174276b01ae17c68ca4271a0e1e

std.Build: document a handful of functions

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

lib/std/Build.zig+15-3
...@@ -290,6 +290,7 @@ const UserValue = union(enum) {...@@ -290,6 +290,7 @@ const UserValue = union(enum) {
290 lazy_path_list: std.array_list.Managed(LazyPath),290 lazy_path_list: std.array_list.Managed(LazyPath),
291};291};
292292
293/// Build system implementation detail.
293pub fn create(294pub fn create(
294 graph: *Graph,295 graph: *Graph,
295 root: Cache.Path,296 root: Cache.Path,
...@@ -681,9 +682,9 @@ fn hashUserInputOptionsMap(allocator: Allocator, user_input_options: UserInputOp...@@ -681,9 +682,9 @@ fn hashUserInputOptionsMap(allocator: Allocator, user_input_options: UserInputOp
681682
682/// Create a set of key-value pairs that can be converted into a Zig source683/// Create a set of key-value pairs that can be converted into a Zig source
683/// file and then inserted into a Zig compilation's module table for importing.684/// file and then inserted into a Zig compilation's module table for importing.
684/// In other words, this provides a way to expose build.zig values to Zig685///
685/// source code with `@import`.686/// This provides a way to expose build.zig values to Zig source code with
686/// Related: `Module.addOptions`.687/// `@import`. Related: `Module.addOptions`.
687pub fn addOptions(b: *Build) *Step.Options {688pub fn addOptions(b: *Build) *Step.Options {
688 return Step.Options.create(b);689 return Step.Options.create(b);
689}690}
...@@ -970,6 +971,7 @@ pub fn addConfigHeader(...@@ -970,6 +971,7 @@ pub fn addConfigHeader(
970 return config_header_step;971 return config_header_step;
971}972}
972973
974/// Deprecated, call `Graph.dupeString` instead.
973pub fn dupe(b: *Build, bytes: []const u8) []const u8 {975pub fn dupe(b: *Build, bytes: []const u8) []const u8 {
974 return b.graph.dupeString(bytes);976 return b.graph.dupeString(bytes);
975}977}
...@@ -1292,6 +1294,8 @@ pub fn option(b: *Build, comptime T: type, name_raw: []const u8, description_raw...@@ -1292,6 +1294,8 @@ pub fn option(b: *Build, comptime T: type, name_raw: []const u8, description_raw
1292 }1294 }
1293}1295}
12941296
1297/// Creates a top-level build step, exposed to the CLI user and advertised in
1298/// the "--help" menu.
1295pub fn step(b: *Build, name: []const u8, description: []const u8) *Step {1299pub fn step(b: *Build, name: []const u8, description: []const u8) *Step {
1296 const graph = b.graph;1300 const graph = b.graph;
1297 const arena = graph.arena;1301 const arena = graph.arena;
...@@ -1476,6 +1480,7 @@ pub fn standardTargetOptionsQueryOnly(b: *Build, args: StandardTargetOptionsArgs...@@ -1476,6 +1480,7 @@ pub fn standardTargetOptionsQueryOnly(b: *Build, args: StandardTargetOptionsArgs
1476 return args.default_target;1480 return args.default_target;
1477}1481}
14781482
1483/// Build system implementation detail.
1479pub fn addUserInputOption(b: *Build, name_raw: []const u8, value_raw: []const u8) error{OutOfMemory}!bool {1484pub fn addUserInputOption(b: *Build, name_raw: []const u8, value_raw: []const u8) error{OutOfMemory}!bool {
1480 const graph = b.graph;1485 const graph = b.graph;
1481 const arena = graph.arena;1486 const arena = graph.arena;
...@@ -1532,6 +1537,7 @@ pub fn addUserInputOption(b: *Build, name_raw: []const u8, value_raw: []const u8...@@ -1532,6 +1537,7 @@ pub fn addUserInputOption(b: *Build, name_raw: []const u8, value_raw: []const u8
1532 return false;1537 return false;
1533}1538}
15341539
1540/// Build system implementation detail.
1535pub fn addUserInputFlag(b: *Build, name_raw: []const u8) error{OutOfMemory}!bool {1541pub fn addUserInputFlag(b: *Build, name_raw: []const u8) error{OutOfMemory}!bool {
1536 const graph = b.graph;1542 const graph = b.graph;
1537 const name = graph.dupeString(name_raw);1543 const name = graph.dupeString(name_raw);
...@@ -1592,6 +1598,7 @@ fn markInvalidUserInput(b: *Build) void {...@@ -1592,6 +1598,7 @@ fn markInvalidUserInput(b: *Build) void {
1592 b.invalid_user_input = true;1598 b.invalid_user_input = true;
1593}1599}
15941600
1601/// Build system implementation detail.
1595pub fn validateUserInputDidItFail(b: *Build) bool {1602pub fn validateUserInputDidItFail(b: *Build) bool {
1596 // Make sure all args are used.1603 // Make sure all args are used.
1597 var it = b.user_input_options.iterator();1604 var it = b.user_input_options.iterator();
...@@ -2178,6 +2185,7 @@ pub inline fn lazyImport(...@@ -2178,6 +2185,7 @@ pub inline fn lazyImport(
2178 comptime unreachable; // Bad @dependencies source2185 comptime unreachable; // Bad @dependencies source
2179}2186}
21802187
2188/// Build system implementation detail.
2181pub fn dependencyFromBuildZig(2189pub fn dependencyFromBuildZig(
2182 b: *Build,2190 b: *Build,
2183 /// The build.zig struct of the dependency, normally obtained by `@import` of the dependency.2191 /// The build.zig struct of the dependency, normally obtained by `@import` of the dependency.
...@@ -2334,6 +2342,7 @@ fn dependencyInner(...@@ -2334,6 +2342,7 @@ fn dependencyInner(
2334 return dep;2342 return dep;
2335}2343}
23362344
2345/// Build system implementation detail.
2337pub fn runBuild(b: *Build, build_zig: anytype) anyerror!void {2346pub fn runBuild(b: *Build, build_zig: anytype) anyerror!void {
2338 switch (@typeInfo(@typeInfo(@TypeOf(build_zig.build)).@"fn".return_type.?)) {2347 switch (@typeInfo(@typeInfo(@TypeOf(build_zig.build)).@"fn".return_type.?)) {
2339 .void => build_zig.build(b),2348 .void => build_zig.build(b),
...@@ -2710,7 +2719,10 @@ pub fn systemIntegrationOption(...@@ -2710,7 +2719,10 @@ pub fn systemIntegrationOption(
27102719
2711test {2720test {
2712 _ = Cache;2721 _ = Cache;
2722 _ = Configuration;
2723 _ = Module;
2713 _ = Step;2724 _ = Step;
2714 _ = Configuration;2725 _ = Configuration;
2715 _ = &findProgram;2726 _ = &findProgram;
2727 _ = abi;
2716}2728}