| ... | ... | @@ -10808,6 +10808,9 @@ const separator = if (builtin.os.tag == .windows) '\\' else '/'; |
| 10808 | 10808 | Some examples of tasks the build system can help with: |
| 10809 | 10809 | </p> |
| 10810 | 10810 | <ul> |
| 10811 | <li>Performing tasks in parallel and caching the results.</li> |
| 10812 | <li>Depending on other projects.</li> |
| 10813 | <li>Providing a package for other projects to depend on.</li> |
| 10811 | 10814 | <li>Creating build artifacts by executing the Zig compiler. This includes |
| 10812 | 10815 | building Zig source code as well as C and C++ source code.</li> |
| 10813 | 10816 | <li>Capturing user-configured options and using those options to configure |
| ... | ... | @@ -10826,148 +10829,10 @@ const separator = if (builtin.os.tag == .windows) '\\' else '/'; |
| 10826 | 10829 | to see a command-line usage help menu. This will include project-specific |
| 10827 | 10830 | options that were declared in the build.zig script. |
| 10828 | 10831 | </p> |
| 10829 | | |
| 10830 | | {#header_open|Building an Executable#} |
| 10831 | | <p>This <code class="file">build.zig</code> file is automatically generated |
| 10832 | | by <kbd>zig init-exe</kbd>.</p> |
| 10833 | | {#code_begin|syntax|build_executable#} |
| 10834 | | const std = @import("std"); |
| 10835 | | |
| 10836 | | // Although this function looks imperative, note that its job is to |
| 10837 | | // declaratively construct a build graph that will be executed by an external |
| 10838 | | // runner. |
| 10839 | | pub fn build(b: *std.Build) void { |
| 10840 | | // Standard target options allows the person running `zig build` to choose |
| 10841 | | // what target to build for. Here we do not override the defaults, which |
| 10842 | | // means any target is allowed, and the default is native. Other options |
| 10843 | | // for restricting supported target set are available. |
| 10844 | | const target = b.standardTargetOptions(.{}); |
| 10845 | | |
| 10846 | | // Standard optimization options allow the person running `zig build` to select |
| 10847 | | // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall. Here we do not |
| 10848 | | // set a preferred release mode, allowing the user to decide how to optimize. |
| 10849 | | const optimize = b.standardOptimizeOption(.{}); |
| 10850 | | |
| 10851 | | const exe = b.addExecutable(.{ |
| 10852 | | .name = "example", |
| 10853 | | // In this case the main source file is merely a path, however, in more |
| 10854 | | // complicated build scripts, this could be a generated file. |
| 10855 | | .root_source_file = .{ .path = "src/main.zig" }, |
| 10856 | | .target = target, |
| 10857 | | .optimize = optimize, |
| 10858 | | }); |
| 10859 | | |
| 10860 | | // This declares intent for the executable to be installed into the |
| 10861 | | // standard location when the user invokes the "install" step (the default |
| 10862 | | // step when running `zig build`). |
| 10863 | | b.installArtifact(exe); |
| 10864 | | |
| 10865 | | // This *creates* a Run step in the build graph, to be executed when another |
| 10866 | | // step is evaluated that depends on it. The next line below will establish |
| 10867 | | // such a dependency. |
| 10868 | | const run_cmd = b.addRunArtifact(exe); |
| 10869 | | |
| 10870 | | // By making the run step depend on the install step, it will be run from the |
| 10871 | | // installation directory rather than directly from within the cache directory. |
| 10872 | | // This is not necessary, however, if the application depends on other installed |
| 10873 | | // files, this ensures they will be present and in the expected location. |
| 10874 | | run_cmd.step.dependOn(b.getInstallStep()); |
| 10875 | | |
| 10876 | | // This allows the user to pass arguments to the application in the build |
| 10877 | | // command itself, like this: `zig build run -- arg1 arg2 etc` |
| 10878 | | if (b.args) |args| { |
| 10879 | | run_cmd.addArgs(args); |
| 10880 | | } |
| 10881 | | |
| 10882 | | // This creates a build step. It will be visible in the `zig build --help` menu, |
| 10883 | | // and can be selected like this: `zig build run` |
| 10884 | | // This will evaluate the `run` step rather than the default, which is "install". |
| 10885 | | const run_step = b.step("run", "Run the app"); |
| 10886 | | run_step.dependOn(&run_cmd.step); |
| 10887 | | |
| 10888 | | // Creates a step for unit testing. This only builds the test executable |
| 10889 | | // but does not run it. |
| 10890 | | const unit_tests = b.addTest(.{ |
| 10891 | | .root_source_file = .{ .path = "src/main.zig" }, |
| 10892 | | .target = target, |
| 10893 | | .optimize = optimize, |
| 10894 | | }); |
| 10895 | | |
| 10896 | | const run_unit_tests = b.addRunArtifact(unit_tests); |
| 10897 | | |
| 10898 | | // Similar to creating the run step earlier, this exposes a `test` step to |
| 10899 | | // the `zig build --help` menu, providing a way for the user to request |
| 10900 | | // running the unit tests. |
| 10901 | | const test_step = b.step("test", "Run unit tests"); |
| 10902 | | test_step.dependOn(&run_unit_tests.step); |
| 10903 | | } |
| 10904 | | {#code_end#} |
| 10905 | | {#header_close#} |
| 10906 | | |
| 10907 | | {#header_open|Building a Library#} |
| 10908 | | <p>This <code class="file">build.zig</code> file is automatically generated |
| 10909 | | by <kbd>zig init-lib</kbd>.</p> |
| 10910 | | {#code_begin|syntax|build_library#} |
| 10911 | | const std = @import("std"); |
| 10912 | | |
| 10913 | | // Although this function looks imperative, note that its job is to |
| 10914 | | // declaratively construct a build graph that will be executed by an external |
| 10915 | | // runner. |
| 10916 | | pub fn build(b: *std.Build) void { |
| 10917 | | // Standard target options allows the person running `zig build` to choose |
| 10918 | | // what target to build for. Here we do not override the defaults, which |
| 10919 | | // means any target is allowed, and the default is native. Other options |
| 10920 | | // for restricting supported target set are available. |
| 10921 | | const target = b.standardTargetOptions(.{}); |
| 10922 | | |
| 10923 | | // Standard optimization options allow the person running `zig build` to select |
| 10924 | | // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall. Here we do not |
| 10925 | | // set a preferred release mode, allowing the user to decide how to optimize. |
| 10926 | | const optimize = b.standardOptimizeOption(.{}); |
| 10927 | | |
| 10928 | | const lib = b.addStaticLibrary(.{ |
| 10929 | | .name = "example", |
| 10930 | | // In this case the main source file is merely a path, however, in more |
| 10931 | | // complicated build scripts, this could be a generated file. |
| 10932 | | .root_source_file = .{ .path = "src/main.zig" }, |
| 10933 | | .target = target, |
| 10934 | | .optimize = optimize, |
| 10935 | | }); |
| 10936 | | |
| 10937 | | // This declares intent for the library to be installed into the standard |
| 10938 | | // location when the user invokes the "install" step (the default step when |
| 10939 | | // running `zig build`). |
| 10940 | | b.installArtifact(lib); |
| 10941 | | |
| 10942 | | // Creates a step for unit testing. This only builds the test executable |
| 10943 | | // but does not run it. |
| 10944 | | const main_tests = b.addTest(.{ |
| 10945 | | .root_source_file = .{ .path = "src/main.zig" }, |
| 10946 | | .target = target, |
| 10947 | | .optimize = optimize, |
| 10948 | | }); |
| 10949 | | |
| 10950 | | const run_main_tests = b.addRunArtifact(main_tests); |
| 10951 | | |
| 10952 | | // This creates a build step. It will be visible in the `zig build --help` menu, |
| 10953 | | // and can be selected like this: `zig build test` |
| 10954 | | // This will evaluate the `test` step rather than the default, which is "install". |
| 10955 | | const test_step = b.step("test", "Run library tests"); |
| 10956 | | test_step.dependOn(&run_main_tests.step); |
| 10957 | | } |
| 10958 | | {#code_end#} |
| 10959 | | {#header_close#} |
| 10960 | | |
| 10961 | | {#header_open|Compiling C Source Code#} |
| 10962 | | <pre>{#syntax#} |
| 10963 | | lib.addCSourceFile(.{ .file = .{ .path = "src/lib.c" }, .flags = &.{ |
| 10964 | | "-Wall", |
| 10965 | | "-Wextra", |
| 10966 | | "-Werror", |
| 10967 | | } }); |
| 10968 | | {#endsyntax#}</pre> |
| 10969 | | {#header_close#} |
| 10970 | | |
| 10832 | <p> |
| 10833 | For the time being, the build system documentation is hosted externally: |
| 10834 | <a href="https://ziglang.org/learn/build-system/">Build System Documentation</a> |
| 10835 | </p> |
| 10971 | 10836 | {#header_close#} |
| 10972 | 10837 | {#header_open|C#} |
| 10973 | 10838 | <p> |
Andrew Kelley <andrew@ziglang.org> 2024-01-18 21:14:44-07:00