From eb80cc2b9ee687313dda77e9c3b328a882ae849e Mon Sep 17 00:00:00 2001
From: Nathan Michaels <nathan@nmichaels.org>
Date: Sun, 5 Jul 2020 18:37:44 -0400
Subject: [PATCH] Add some basic examples for the Zig Build System.

---
 doc/langref.html.in | 99 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 95 insertions(+), 4 deletions(-)

diff --git a/doc/langref.html.in b/doc/langref.html.in
index 12af3eaadd..0a44203b55 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -8550,7 +8550,8 @@ fn foo(comptime T: type, ptr: *T) T {
       {#header_open|opaque#}
       <p>
       {#syntax#}opaque {}{#endsyntax#} declares a new type with an unknown (but non-zero) size and alignment.
-      It can have declarations like structs, unions, or enums.
+      It can contain declarations the same as {#link|structs|struct#}, {#link|unions|union#},
+      and {#link|enums|enum#}.
       </p>
       <p>
       This is typically used for type safety when interacting with C code that does not expose struct details.
@@ -9626,9 +9627,99 @@ test "assert in release fast mode" {
       </p>
       {#header_close#}
       {#header_open|Zig Build System#}
-      <p>TODO: explain purpose, it's supposed to replace make/cmake</p>
-      <p>TODO: example of building a zig executable</p>
-      <p>TODO: example of building a C library</p>
+
+      <p>Simple programs can be built with {#syntax#}zig
+      build-exe{#endsyntax#} and {#syntax#}zig build-lib{#endsyntax#},
+      but running those commands manually gets tedious and error
+      prone. Zig's build system lets you keep all the command line
+      switches and build modes in one place. It has no external
+      dependencies, so Zig code can be built on any platform without
+      installing more programs.</p>
+      <p>To use the build system, run 
+      <code class="shell">$ zig build [command]</code>
+      where {#syntax#}[command]{#endsyntax#} is an optional target,
+      configured by your build.zig file. There is more detail
+      on <a href="https://github.com/ziglang/zig/wiki/Zig-Build-System">the
+      wiki</a> but here are some example build.zig files to get you
+      started:</p>
+      
+      {#header_open|Building a Zig Executable#}
+      <p>This <code>build.zig</code> file is automatically generated
+        by <code>zig init-exe</code>.</p>
+      {#code_begin|syntax|build#}
+const Builder = @import("std").build.Builder;
+
+pub fn build(b: *Builder) 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 release options allow the person running `zig build` to select
+    // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall.
+    const mode = b.standardReleaseOptions();
+
+    // This line tells the Zig build system where to find the file
+    // that contains main and what to call the executable.
+    const exe = b.addExecutable("main", "src/main.zig");
+    exe.setTarget(target);
+    exe.setBuildMode(mode);
+    exe.install();
+
+    const run_cmd = exe.run();
+    run_cmd.step.dependOn(b.getInstallStep());
+
+    // This will be executed by "zig build run"
+    const run_step = b.step("run", "Run the app");
+    run_step.dependOn(&run_cmd.step);
+}
+      {#code_end#}{#header_close#}
+
+      {#header_open|Building a C library#}
+      {#code_begin|syntax#}
+      const Builder = @import("std").build.Builder;
+
+      pub fn build(b: *Builder) void {
+          const mode = b.standardReleaseOptions();
+          // Add a target that generates libbadmath, with no Zig source files.
+          const lib = b.addStaticLibrary("badmath", null);
+          lib.setBuildMode(mode);
+          // This particular library exists entirely in src/lib.c.
+          lib.addCSourceFile("src/lib.c", &[_][]const u8{
+              "-Wall",
+              "-Wextra",
+              "-Werror",
+          });
+          // libbadmath.a will be put in this directory, instead of only
+          // living in zig-cache.
+          lib.setOutputDir("obj");
+          lib.install();
+      }
+      {#code_end#}
+      {#header_close#}
+
+      {#header_open|Extending a C library#}
+      {#code_begin|syntax#}
+const Builder = @import("std").build.Builder;
+
+pub fn build(b: *Builder) void {
+    const mode = b.standardReleaseOptions();
+    // This line tells the build system to make a static library
+    // called "add" using source from "src/main.zig".
+    const lib = b.addStaticLibrary("add", "src/main.zig");
+    lib.setBuildMode(mode);
+    lib.force_pic = true;
+    // Include the compiler's runtime environment in the static library.
+    lib.bundle_compiler_rt = true;
+
+    var main_tests = b.addTest("src/main.zig");
+    main_tests.setBuildMode(mode);
+
+    const test_step = b.step("test", "Run library tests");
+    test_step.dependOn(&main_tests.step);
+}
+      {#code_end#}{#header_close#}
       {#header_close#}
       {#header_open|C#}
       <p>