|
| 1 | +const std = @import("std"); |
| 2 | + |
| 3 | +// Although this function looks imperative, it does not perform the build |
| 4 | +// directly and instead it mutates the build graph (`b`) that will be then |
| 5 | +// executed by an external runner. The functions in `std.Build` implement a DSL |
| 6 | +// for defining build steps and express dependencies between them, allowing the |
| 7 | +// build runner to parallelize the build automatically (and the cache system to |
| 8 | +// know when a step doesn't need to be re-run). |
| 9 | +pub fn build(b: *std.Build) void { |
| 10 | + // Standard target options allow the person running `zig build` to choose |
| 11 | + // what target to build for. Here we do not override the defaults, which |
| 12 | + // means any target is allowed, and the default is native. Other options |
| 13 | + // for restricting supported target set are available. |
| 14 | + const target = b.standardTargetOptions(.{}); |
| 15 | + // Standard optimization options allow the person running `zig build` to select |
| 16 | + // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall. Here we do not |
| 17 | + // set a preferred release mode, allowing the user to decide how to optimize. |
| 18 | + const optimize = b.standardOptimizeOption(.{}); |
| 19 | + // It's also possible to define more custom flags to toggle optional features |
| 20 | + // of this build script using `b.option()`. All defined flags (including |
| 21 | + // target and optimize options) will be listed when running `zig build --help` |
| 22 | + // in this directory. |
| 23 | + |
| 24 | + // This creates a module, which represents a collection of source files alongside |
| 25 | + // some compilation options, such as optimization mode and linked system libraries. |
| 26 | + // Zig modules are the preferred way of making Zig code available to consumers. |
| 27 | + // addModule defines a module that we intend to make available for importing |
| 28 | + // to our consumers. We must give it a name because a Zig package can expose |
| 29 | + // multiple modules and consumers will need to be able to specify which |
| 30 | + // module they want to access. |
| 31 | + const mod = b.addModule("zig", .{ |
| 32 | + // The root source file is the "entry point" of this module. Users of |
| 33 | + // this module will only be able to access public declarations contained |
| 34 | + // in this file, which means that if you have declarations that you |
| 35 | + // intend to expose to consumers that were defined in other files part |
| 36 | + // of this module, you will have to make sure to re-export them from |
| 37 | + // the root file. |
| 38 | + .root_source_file = b.path("src/root.zig"), |
| 39 | + // Later on we'll use this module as the root module of a test executable |
| 40 | + // which requires us to specify a target. |
| 41 | + .target = target, |
| 42 | + }); |
| 43 | + |
| 44 | + // Here we define an executable. An executable needs to have a root module |
| 45 | + // which needs to expose a `main` function. While we could add a main function |
| 46 | + // to the module defined above, it's sometimes preferable to split business |
| 47 | + // logic and the CLI into two separate modules. |
| 48 | + // |
| 49 | + // If your goal is to create a Zig library for others to use, consider if |
| 50 | + // it might benefit from also exposing a CLI tool. A parser library for a |
| 51 | + // data serialization format could also bundle a CLI syntax checker, for example. |
| 52 | + // |
| 53 | + // If instead your goal is to create an executable, consider if users might |
| 54 | + // be interested in also being able to embed the core functionality of your |
| 55 | + // program in their own executable in order to avoid the overhead involved in |
| 56 | + // subprocessing your CLI tool. |
| 57 | + // |
| 58 | + // If neither case applies to you, feel free to delete the declaration you |
| 59 | + // don't need and to put everything under a single module. |
| 60 | + const exe = b.addExecutable(.{ |
| 61 | + .name = "zig", |
| 62 | + .root_module = b.createModule(.{ |
| 63 | + // b.createModule defines a new module just like b.addModule but, |
| 64 | + // unlike b.addModule, it does not expose the module to consumers of |
| 65 | + // this package, which is why in this case we don't have to give it a name. |
| 66 | + .root_source_file = b.path("src/main.zig"), |
| 67 | + // Target and optimization levels must be explicitly wired in when |
| 68 | + // defining an executable or library (in the root module), and you |
| 69 | + // can also hardcode a specific target for an executable or library |
| 70 | + // definition if desireable (e.g. firmware for embedded devices). |
| 71 | + .target = target, |
| 72 | + .optimize = optimize, |
| 73 | + // List of modules available for import in source files part of the |
| 74 | + // root module. |
| 75 | + .imports = &.{ |
| 76 | + // Here "zig" is the name you will use in your source code to |
| 77 | + // import this module (e.g. `@import("zig")`). The name is |
| 78 | + // repeated because you are allowed to rename your imports, which |
| 79 | + // can be extremely useful in case of collisions (which can happen |
| 80 | + // importing modules from different packages). |
| 81 | + .{ .name = "zig", .module = mod }, |
| 82 | + }, |
| 83 | + }), |
| 84 | + }); |
| 85 | + |
| 86 | + // This declares intent for the executable to be installed into the |
| 87 | + // install prefix when running `zig build` (i.e. when executing the default |
| 88 | + // step). By default the install prefix is `zig-out/` but can be overridden |
| 89 | + // by passing `--prefix` or `-p`. |
| 90 | + b.installArtifact(exe); |
| 91 | + |
| 92 | + // This creates a top level step. Top level steps have a name and can be |
| 93 | + // invoked by name when running `zig build` (e.g. `zig build run`). |
| 94 | + // This will evaluate the `run` step rather than the default step. |
| 95 | + // For a top level step to actually do something, it must depend on other |
| 96 | + // steps (e.g. a Run step, as we will see in a moment). |
| 97 | + const run_step = b.step("run", "Run the app"); |
| 98 | + |
| 99 | + // This creates a RunArtifact step in the build graph. A RunArtifact step |
| 100 | + // invokes an executable compiled by Zig. Steps will only be executed by the |
| 101 | + // runner if invoked directly by the user (in the case of top level steps) |
| 102 | + // or if another step depends on it, so it's up to you to define when and |
| 103 | + // how this Run step will be executed. In our case we want to run it when |
| 104 | + // the user runs `zig build run`, so we create a dependency link. |
| 105 | + const run_cmd = b.addRunArtifact(exe); |
| 106 | + run_step.dependOn(&run_cmd.step); |
| 107 | + |
| 108 | + // By making the run step depend on the default step, it will be run from the |
| 109 | + // installation directory rather than directly from within the cache directory. |
| 110 | + run_cmd.step.dependOn(b.getInstallStep()); |
| 111 | + |
| 112 | + // This allows the user to pass arguments to the application in the build |
| 113 | + // command itself, like this: `zig build run -- arg1 arg2 etc` |
| 114 | + if (b.args) |args| { |
| 115 | + run_cmd.addArgs(args); |
| 116 | + } |
| 117 | + |
| 118 | + // Creates an executable that will run `test` blocks from the provided module. |
| 119 | + // Here `mod` needs to define a target, which is why earlier we made sure to |
| 120 | + // set the releative field. |
| 121 | + const mod_tests = b.addTest(.{ |
| 122 | + .root_module = mod, |
| 123 | + }); |
| 124 | + |
| 125 | + // A run step that will run the test executable. |
| 126 | + const run_mod_tests = b.addRunArtifact(mod_tests); |
| 127 | + |
| 128 | + // Creates an executable that will run `test` blocks from the executable's |
| 129 | + // root module. Note that test executables only test one module at a time, |
| 130 | + // hence why we have to create two separate ones. |
| 131 | + const exe_tests = b.addTest(.{ |
| 132 | + .root_module = exe.root_module, |
| 133 | + }); |
| 134 | + |
| 135 | + // A run step that will run the second test executable. |
| 136 | + const run_exe_tests = b.addRunArtifact(exe_tests); |
| 137 | + |
| 138 | + // A top level step for running all tests. dependOn can be called multiple |
| 139 | + // times and since the two run steps do not depend on one another, this will |
| 140 | + // make the two of them run in parallel. |
| 141 | + const test_step = b.step("test", "Run tests"); |
| 142 | + test_step.dependOn(&run_mod_tests.step); |
| 143 | + test_step.dependOn(&run_exe_tests.step); |
| 144 | + |
| 145 | + // Just like flags, top level steps are also listed in the `--help` menu. |
| 146 | + // |
| 147 | + // The Zig build system is entirely implemented in userland, which means |
| 148 | + // that it cannot hook into private compiler APIs. All compilation work |
| 149 | + // orchestrated by the build system will result in other Zig compiler |
| 150 | + // subcommands being invoked with the right flags defined. You can observe |
| 151 | + // these invocations when one fails (or you pass a flag to increase |
| 152 | + // verbosity) to validate assumptions and diagnose problems. |
| 153 | + // |
| 154 | + // Lastly, the Zig build system is relatively simple and self-contained, |
| 155 | + // and reading its source code will allow you to master it. |
| 156 | +} |
0 commit comments