Commit 6822a7a1237d0274ac68b9e713db11c45a737998 | zig

author	dbandstra <dbandstra@protonmail.com> 2023-08-06 14:55:57-07:00
committer	Andrew Kelley <andrew@ziglang.org> 2023-10-20 04:50:29-04:00
log	6822a7a1237d0274ac68b9e713db11c45a737998
tree	75e2b6dea1de70028f851b4561a1afbf2753cd0d
parent	3c22cecee20d0c01d6c007c4fb8a8903498c66db

langref: bring build.zig examples up to date

Update to match current outputs of init-exe and init-lib.

1 files changed, 18 insertions(+), 0 deletions(-)

doc
- langref.html.in

doc/langref.html.in+18

 @@ -10836,12 +10836,25 @@ pub fn build(b: *std.Build) void {
       {#code_begin|syntax|build_library#}
 const std = @import("std");
+// Although this function looks imperative, note that its job is to
+// declaratively construct a build graph that will be executed by an external
+// runner.
 pub fn build(b: *std.Build) void {
+    // Standard target options allows the person running `zig build` to choose
+    // what target to build for. Here we do not override the defaults, which
+    // means any target is allowed, and the default is native. Other options
+    // for restricting supported target set are available.
     const target = b.standardTargetOptions(.{});
+    // Standard optimization options allow the person running `zig build` to select
+    // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall. Here we do not
+    // set a preferred release mode, allowing the user to decide how to optimize.
     const optimize = b.standardOptimizeOption(.{});
     const lib = b.addStaticLibrary(.{
         .name = "example",
+        // In this case the main source file is merely a path, however, in more
+        // complicated build scripts, this could be a generated file.
         .root_source_file = .{ .path = "src/main.zig" },
         .target = target,
         .optimize = optimize,
 @@ -10852,6 +10865,8 @@ pub fn build(b: *std.Build) void {
     // running `zig build`).
     b.installArtifact(lib);
+    // Creates a step for unit testing. This only builds the test executable
+    // but does not run it.
     const main_tests = b.addTest(.{
         .root_source_file = .{ .path = "src/main.zig" },
         .target = target,
 @@ -10860,6 +10875,9 @@ pub fn build(b: *std.Build) void {
     const run_main_tests = b.addRunArtifact(main_tests);
+    // This creates a build step. It will be visible in the `zig build --help` menu,
+    // and can be selected like this: `zig build test`
+    // This will evaluate the `test` step rather than the default, which is "install".
     const test_step = b.step("test", "Run library tests");
     test_step.dependOn(&run_main_tests.step);
 }