commit 56db624643bb506d2b8fa9d81f4146c1b1f4e3c3 (tree)
parent 8662c0ff43aad7191b063047c71384e868086d6f
Author: Andrew Kelley <andrew@ziglang.org>
Date: Thu, 18 Jan 2024 21:14:44 -0700
langref: update Zig Build System section
It's hosted externally for now.
closes #18103
Diffstat:
| M | doc/langref.html.in | | | 149 | ++++--------------------------------------------------------------------------- |
1 file changed, 7 insertions(+), 142 deletions(-)
diff --git a/doc/langref.html.in b/doc/langref.html.in
@@ -10808,6 +10808,9 @@ const separator = if (builtin.os.tag == .windows) '\\' else '/';
Some examples of tasks the build system can help with:
</p>
<ul>
+ <li>Performing tasks in parallel and caching the results.</li>
+ <li>Depending on other projects.</li>
+ <li>Providing a package for other projects to depend on.</li>
<li>Creating build artifacts by executing the Zig compiler. This includes
building Zig source code as well as C and C++ source code.</li>
<li>Capturing user-configured options and using those options to configure
@@ -10826,148 +10829,10 @@ const separator = if (builtin.os.tag == .windows) '\\' else '/';
to see a command-line usage help menu. This will include project-specific
options that were declared in the build.zig script.
</p>
-
- {#header_open|Building an Executable#}
- <p>This <code class="file">build.zig</code> file is automatically generated
- by <kbd>zig init-exe</kbd>.</p>
- {#code_begin|syntax|build_executable#}
-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 exe = b.addExecutable(.{
- .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,
- });
-
- // This declares intent for the executable to be installed into the
- // standard location when the user invokes the "install" step (the default
- // step when running `zig build`).
- b.installArtifact(exe);
-
- // This *creates* a Run step in the build graph, to be executed when another
- // step is evaluated that depends on it. The next line below will establish
- // such a dependency.
- const run_cmd = b.addRunArtifact(exe);
-
- // By making the run step depend on the install step, it will be run from the
- // installation directory rather than directly from within the cache directory.
- // This is not necessary, however, if the application depends on other installed
- // files, this ensures they will be present and in the expected location.
- run_cmd.step.dependOn(b.getInstallStep());
-
- // This allows the user to pass arguments to the application in the build
- // command itself, like this: `zig build run -- arg1 arg2 etc`
- if (b.args) |args| {
- run_cmd.addArgs(args);
- }
-
- // This creates a build step. It will be visible in the `zig build --help` menu,
- // and can be selected like this: `zig build run`
- // This will evaluate the `run` step rather than the default, which is "install".
- const run_step = b.step("run", "Run the app");
- run_step.dependOn(&run_cmd.step);
-
- // Creates a step for unit testing. This only builds the test executable
- // but does not run it.
- const unit_tests = b.addTest(.{
- .root_source_file = .{ .path = "src/main.zig" },
- .target = target,
- .optimize = optimize,
- });
-
- const run_unit_tests = b.addRunArtifact(unit_tests);
-
- // Similar to creating the run step earlier, this exposes a `test` step to
- // the `zig build --help` menu, providing a way for the user to request
- // running the unit tests.
- const test_step = b.step("test", "Run unit tests");
- test_step.dependOn(&run_unit_tests.step);
-}
- {#code_end#}
- {#header_close#}
-
- {#header_open|Building a Library#}
- <p>This <code class="file">build.zig</code> file is automatically generated
- by <kbd>zig init-lib</kbd>.</p>
- {#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,
- });
-
- // This declares intent for the library to be installed into the standard
- // location when the user invokes the "install" step (the default step when
- // 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,
- .optimize = optimize,
- });
-
- 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);
-}
- {#code_end#}
- {#header_close#}
-
- {#header_open|Compiling C Source Code#}
- <pre>{#syntax#}
-lib.addCSourceFile(.{ .file = .{ .path = "src/lib.c" }, .flags = &.{
- "-Wall",
- "-Wextra",
- "-Werror",
- } });
- {#endsyntax#}</pre>
- {#header_close#}
-
+ <p>
+ For the time being, the build system documentation is hosted externally:
+ <a href="https://ziglang.org/learn/build-system/">Build System Documentation</a>
+ </p>
{#header_close#}
{#header_open|C#}
<p>
